From 09e8947cf76015f980b0488f868da66397b77975 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 09:05:08 -0500
Subject: [PATCH 01/24] Fix variant on dbupdate.twig

---
 resources/templates/_special/dbupdate.twig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/templates/_special/dbupdate.twig b/resources/templates/_special/dbupdate.twig
index caf0838ad78..24d9bb64b18 100644
--- a/resources/templates/_special/dbupdate.twig
+++ b/resources/templates/_special/dbupdate.twig
@@ -6,6 +6,6 @@
     <form method="post" action="{{ cpUrl('updates') }}" class="buttons">
         {{ csrfInput() }}
         {{ hiddenInput('return', Request.path()) }}
-        <button type="submit" class="btn submit">{{ 'Finish up'|t('app') }}</button>
+      <craft-button type="submit" variant="primary">{{ 'Finish up'|t('app') }}</craft-button>
     </form>
 {% endblock %}

From ae78c73de58dcf271bfb8d49e673282dcc13581d Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 09:13:54 -0500
Subject: [PATCH 02/24] Cleanup "New entry type" button

---
 resources/js/pages/settings/entry-types/Index.vue | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/resources/js/pages/settings/entry-types/Index.vue b/resources/js/pages/settings/entry-types/Index.vue
index d56de549b2f..2e8f31521db 100644
--- a/resources/js/pages/settings/entry-types/Index.vue
+++ b/resources/js/pages/settings/entry-types/Index.vue
@@ -145,10 +145,9 @@
 <template>
   <LayoutSlot name="actions">
     <CpLink
-      appearance="button"
+      as="craft-button"
       :href="create().url"
-      variant="accent"
-      :inertia="false"
+      variant="primary"
       icon="plus"
     >
       {{ t('New entry type') }}

From 4766b9f0e8b36109755639e8772d7f0543b67e71 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 12:32:05 -0500
Subject: [PATCH 03/24] Baseline cleanup

---
 packages/craftcms-legacy/cp/src/css/_main.scss     |  7 -------
 .../base-element-select-input.ts                   | 14 +++++++-------
 .../elements/components/ElementEditScreen.vue      |  6 ++----
 .../js/modules/forms/ElementSelectControl.vue      |  9 ++++++---
 resources/js/pages/Form.vue                        |  4 ++--
 resources/js/pages/settings/entry-types/Index.vue  | 12 +++---------
 6 files changed, 20 insertions(+), 32 deletions(-)

diff --git a/packages/craftcms-legacy/cp/src/css/_main.scss b/packages/craftcms-legacy/cp/src/css/_main.scss
index 8ad7937e8d3..9c4d25d659d 100644
--- a/packages/craftcms-legacy/cp/src/css/_main.scss
+++ b/packages/craftcms-legacy/cp/src/css/_main.scss
@@ -271,7 +271,6 @@ body.rtl [data-icon-after='structure']::after {
   content: 'ellipsis' / '';
 }
 
-
 /* paragraphs */
 p {
   margin-block: 1em;
@@ -2975,12 +2974,6 @@ table:not(.cp-table) {
 .chips {
   align-items: flex-start;
   gap: var(--xs);
-
-  &.chips-small {
-    li {
-      height: calc(34rem / 16);
-    }
-  }
 }
 
 .inline-chips {
diff --git a/resources/js/modules/element-select-input/base-element-select-input.ts b/resources/js/modules/element-select-input/base-element-select-input.ts
index a862ec68b95..8dc8fc503b4 100644
--- a/resources/js/modules/element-select-input/base-element-select-input.ts
+++ b/resources/js/modules/element-select-input/base-element-select-input.ts
@@ -1,15 +1,15 @@
 import {
+  BACKSPACE_KEY,
   Base,
-  Select,
-  DragSort,
-  CustomSelect,
   bod,
-  firstFocusableElement,
-  hasAttr,
-  BACKSPACE_KEY,
+  CustomSelect,
   DELETE_KEY,
   DOWN_KEY,
+  DragSort,
+  firstFocusableElement,
+  hasAttr,
   RETURN_KEY,
+  Select,
   UP_KEY,
 } from '@craftcms/garnish';
 import {elementSelectInputData} from './support';
@@ -278,7 +278,7 @@ export class BaseElementSelectInput extends Base {
   }
 
   getAddElementsBtn(): any {
-    return this.$container.find('.btn.add:first');
+    return this.$container.find('[command="--add-element"]');
   }
 
   getSpinner(): any {
diff --git a/resources/js/modules/elements/components/ElementEditScreen.vue b/resources/js/modules/elements/components/ElementEditScreen.vue
index 463f93f3ab8..5558026d8e8 100644
--- a/resources/js/modules/elements/components/ElementEditScreen.vue
+++ b/resources/js/modules/elements/components/ElementEditScreen.vue
@@ -18,9 +18,7 @@
   import {computed} from 'vue';
   import {router} from '@inertiajs/vue3';
   import AppLayout from '@/common/layouts/AppLayout.vue';
-  import Breadcrumbs, {
-    type BreadcrumbItem,
-  } from '@/common/components/Breadcrumbs.vue';
+  import {type BreadcrumbItem} from '@/common/components/Breadcrumbs.vue';
   import DynamicHtmlRenderer from '@/common/components/DynamicHtmlRenderer.vue';
   import FormActions from '@/common/components/FormActions.vue';
   import ErrorSummary from '@/common/form/ErrorSummary.vue';
@@ -269,7 +267,7 @@
           >
             <div class="element-editor__content">
               <craft-pane padding="none" appearance="plain">
-                <div class="py-1">
+                <div class="py-4">
                   <!-- Tabs are rendered by `FormNodeList` inside the form itself. -->
                   <div class="element-form">
                     <FormRenderer
diff --git a/resources/js/modules/forms/ElementSelectControl.vue b/resources/js/modules/forms/ElementSelectControl.vue
index 7b0a539f659..93daf548074 100644
--- a/resources/js/modules/forms/ElementSelectControl.vue
+++ b/resources/js/modules/forms/ElementSelectControl.vue
@@ -168,14 +168,17 @@
       </ul>
 
       <div v-if="editable" class="flex">
-        <button
+        <craft-button
           type="button"
-          class="btn add icon dashed wrap"
+          variant="dashed"
+          icon="plus"
+          command="--add-element"
           data-element-select-add
           :aria-label="control.props.selectionLabel"
+          @click=""
         >
           {{ control.props.selectionLabel }}
-        </button>
+        </craft-button>
         <div class="spinner hidden" />
       </div>
     </component>
diff --git a/resources/js/pages/Form.vue b/resources/js/pages/Form.vue
index cba972e61a8..2045a037e34 100644
--- a/resources/js/pages/Form.vue
+++ b/resources/js/pages/Form.vue
@@ -105,8 +105,8 @@
 
 <template>
   <form @submit.prevent="save()">
-    <craft-pane appearance="raised">
-      <craft-field-group>
+    <craft-pane appearance="raised" padding="none">
+      <craft-field-group class="py-4">
         <FormRenderer
           ref="renderer"
           :payload="form"
diff --git a/resources/js/pages/settings/entry-types/Index.vue b/resources/js/pages/settings/entry-types/Index.vue
index 2e8f31521db..41573f0ccb7 100644
--- a/resources/js/pages/settings/entry-types/Index.vue
+++ b/resources/js/pages/settings/entry-types/Index.vue
@@ -5,12 +5,11 @@
   import {type PaginationData, type SortItem} from '@/common/types';
   import {computed, h, ref} from 'vue';
   import DynamicHtmlRenderer from '@/common/components/DynamicHtmlRenderer.vue';
-  import {router} from '@inertiajs/vue3';
+  import {Link, router} from '@inertiajs/vue3';
   import {create, destroy, index} from '@actions/Settings/EntryTypesController';
   import {useServerPagination} from '@/modules/admin-table/composables/useServerPagination';
   import SearchForm from '@/modules/admin-table/components/SearchForm.vue';
   import {useServerSort} from '@/modules/admin-table/composables/useServerSort';
-  import CpLink from '@/common/components/CpLink.vue';
   import Empty from '@/common/components/Empty.vue';
   import DeleteButton from '@/modules/admin-table/components/DeleteButton.vue';
   import {createCraftColumnHelper} from '@/modules/admin-table/helpers/createCraftColumnHelper';
@@ -144,14 +143,9 @@
 
 <template>
   <LayoutSlot name="actions">
-    <CpLink
-      as="craft-button"
-      :href="create().url"
-      variant="primary"
-      icon="plus"
-    >
+    <Link as="craft-button" :href="create().url" variant="primary" icon="plus">
       {{ t('New entry type') }}
-    </CpLink>
+    </Link>
   </LayoutSlot>
 
   <craft-pane padding="0" appearance="raised">

From af53957f24945891b06accb8063f630d9359abaf Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 12:44:32 -0500
Subject: [PATCH 04/24] Own the element selector modal registry

The modal classes were ported to modern TypeScript, but the registry that
resolves one for an element type stayed in the legacy bundle -- so the
modern module had to reach back into `Craft._elementSelectorModalClasses`
to register its own asset modal.

The registry and factory move here. In-repo callers import
`createElementSelectorModal` directly instead of going through `Craft`,
and the legacy trio is deleted from `Craft.js`.

`Craft.createElementSelectorModal` and `registerElementSelectorModalClass`
are still assigned, so plugins are unaffected, as are the PHP-emitted
`new Craft.VolumeFolderSelectorModal(...)` boots. The legacy bundle runs
before this module, so anything already sitting on the old registry object
is adopted on load, and the built-in asset registration yields to it.
---
 packages/craftcms-legacy/cp/src/js/Craft.js   | 37 ---------
 .../base-element-select-input.ts              |  3 +-
 .../modules/element-selector-modal/README.md  | 58 ++++++++++++++
 .../element-selector-modal/index.test.ts      | 28 ++++++-
 .../modules/element-selector-modal/index.ts   | 39 ++++++----
 .../element-selector-modal/registry.test.ts   | 75 ++++++++++++++++++
 .../element-selector-modal/registry.ts        | 76 +++++++++++++++++++
 .../js/modules/link-field/craft-link-field.ts |  3 +-
 .../markdown-field/behaviors/assets.ts        | 32 ++++----
 9 files changed, 279 insertions(+), 72 deletions(-)
 create mode 100644 resources/js/modules/element-selector-modal/README.md
 create mode 100644 resources/js/modules/element-selector-modal/registry.test.ts
 create mode 100644 resources/js/modules/element-selector-modal/registry.ts

diff --git a/packages/craftcms-legacy/cp/src/js/Craft.js b/packages/craftcms-legacy/cp/src/js/Craft.js
index c1bfc1daeaf..5989126a745 100644
--- a/packages/craftcms-legacy/cp/src/js/Craft.js
+++ b/packages/craftcms-legacy/cp/src/js/Craft.js
@@ -1990,7 +1990,6 @@ $.extend(Craft, {
   },
 
   _elementIndexClasses: {},
-  _elementSelectorModalClasses: {},
   _elementEditorClasses: {},
   _uploaderClasses: {},
   _authFormHandlers: {},
@@ -2031,24 +2030,6 @@ $.extend(Craft, {
     this._uploaderClasses[fsType] = func;
   },
 
-  /**
-   * Registers an element selector modal class for a given element type.
-   *
-   * @param {string} elementType
-   * @param {function} func
-   */
-  registerElementSelectorModalClass: function (elementType, func) {
-    if (typeof this._elementSelectorModalClasses[elementType] !== 'undefined') {
-      throw (
-        'An element selector modal class has already been registered for the element type “' +
-        elementType +
-        '”.'
-      );
-    }
-
-    this._elementSelectorModalClasses[elementType] = func;
-  },
-
   registerAuthFormHandler(method, func) {
     if (typeof this._authFormHandlers[method] !== 'undefined') {
       throw `An authentication form handler has already been registered for the method “${method}”.`;
@@ -2097,24 +2078,6 @@ $.extend(Craft, {
     return uploader;
   },
 
-  /**
-   * Creates a new element selector modal for a given element type.
-   *
-   * @param {string} elementType
-   * @param {Object} settings
-   */
-  createElementSelectorModal: function (elementType, settings) {
-    var func;
-
-    if (typeof this._elementSelectorModalClasses[elementType] !== 'undefined') {
-      func = this._elementSelectorModalClasses[elementType];
-    } else {
-      func = Craft.BaseElementSelectorModal;
-    }
-
-    return new func(elementType, settings);
-  },
-
   /**
    * @deprecated in 6.0. Use event listeners directly.
    */
diff --git a/resources/js/modules/element-select-input/base-element-select-input.ts b/resources/js/modules/element-select-input/base-element-select-input.ts
index 8dc8fc503b4..13563b2ee13 100644
--- a/resources/js/modules/element-select-input/base-element-select-input.ts
+++ b/resources/js/modules/element-select-input/base-element-select-input.ts
@@ -12,6 +12,7 @@ import {
   Select,
   UP_KEY,
 } from '@craftcms/garnish';
+import {createElementSelectorModal} from '@/modules/element-selector-modal/registry';
 import {elementSelectInputData} from './support';
 
 declare const Craft: any;
@@ -914,7 +915,7 @@ export class BaseElementSelectInput extends Base {
   }
 
   createModal(): any {
-    return Craft.createElementSelectorModal(
+    return createElementSelectorModal(
       this.settings.elementType,
       this.getModalSettings()
     );
diff --git a/resources/js/modules/element-selector-modal/README.md b/resources/js/modules/element-selector-modal/README.md
new file mode 100644
index 00000000000..363277c0258
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/README.md
@@ -0,0 +1,58 @@
+# element-selector-modal
+
+Replaces `Craft.BaseElementSelectorModal` / `Craft.AssetSelectorModal` /
+`Craft.VolumeFolderSelectorModal` from the legacy cp bundle, plus the
+`createElementSelectorModal` / `registerElementSelectorModalClass` registry that
+used to live in `cp/src/js/Craft.js`.
+
+## Shape
+
+This module does **not** follow the `<name>.ce.ts` + `support.ts` shape described
+in [the modules README](../README.md). That pattern is for behavior wrapped
+around server-rendered markup; a selector modal has none — it is constructed
+imperatively and builds its own container. So there is no custom element and no
+element-keyed instance registry.
+
+What does carry over is the rest of the pattern: the module owns the behavior,
+`window.Craft.*` is a shim, and the legacy source is deleted.
+
+| File | Role |
+| --- | --- |
+| `base-element-selector-modal.ts` | The base modal, on `@craftcms/garnish` `Modal`. |
+| `asset-selector-modal.ts` | Adds the "Select transform" menu. |
+| `volume-folder-selector-modal.ts` | Folder picker used by asset moves. |
+| `registry.ts` | Element type → modal class map, and the factory. |
+| `index.ts` | Registers the built-in asset mapping, assigns the `Craft.*` shims, re-exports. |
+
+## Registry
+
+`registry.ts` holds the map. `createElementSelectorModal(elementType, settings)`
+constructs the registered class, or `BaseElementSelectorModal`.
+`registerElementSelectorModalClass()` throws on a duplicate, as the legacy
+registry did.
+
+In-repo callers import the factory directly rather than going through `Craft`.
+The globals remain for plugins and for PHP-emitted boots — `MoveAssets.php` and
+the legacy `AssetIndex` still emit `new Craft.VolumeFolderSelectorModal(…)`.
+
+### Load order
+
+The legacy bundle is a plain `<script>` and runs before this module, so a plugin
+can register a class before there is anywhere modern to put it.
+`adoptLegacyRegistrations()` drains anything sitting on
+`Craft._elementSelectorModalClasses` on load, and the built-in asset registration
+yields to an entry that is already there.
+
+That covers a plugin assigning into the object. A plugin *calling*
+`Craft.registerElementSelectorModalClass()` before this module evaluates will
+still fail — the function no longer exists in the legacy bundle. If that turns up
+in practice, the fix is a queueing stub in the legacy bundle, not moving the
+registry back.
+
+## Still jQuery
+
+`base-element-selector-modal.ts` builds its chrome with jQuery (`$body`,
+`$footer`, `Craft.ui.createSubmitButton`) and binds the jQuery-synthetic
+`doubletap` event. The element index inside the modal is still the legacy
+`Craft.AssetIndex` / `BaseElementIndex` via the `Craft.createElementIndex` seam —
+the next registry worth porting the same way.
diff --git a/resources/js/modules/element-selector-modal/index.test.ts b/resources/js/modules/element-selector-modal/index.test.ts
index 460a2410733..05a1234b6d1 100644
--- a/resources/js/modules/element-selector-modal/index.test.ts
+++ b/resources/js/modules/element-selector-modal/index.test.ts
@@ -5,8 +5,32 @@ afterEach(() => {
   vi.resetModules();
 });
 
-it('loads without the legacy selector modal registry', async () => {
+it('owns the registry rather than reaching into the legacy bundle', async () => {
   vi.stubGlobal('Craft', {});
 
-  await expect(import('./index')).resolves.toBeDefined();
+  const module = await import('./index');
+  const Craft = (window as any).Craft;
+
+  // The factory and the registration hook now come from here, so the legacy
+  // bundle no longer has to ship either.
+  expect(typeof Craft.createElementSelectorModal).toBe('function');
+  expect(typeof Craft.registerElementSelectorModalClass).toBe('function');
+  expect(
+    module.elementSelectorModalClass('CraftCms\\Cms\\Asset\\Elements\\Asset')
+  ).toBe(module.AssetSelectorModal);
+});
+
+it('yields to a modal class the legacy bundle already registered for assets', async () => {
+  class PluginAssetModal {}
+  vi.stubGlobal('Craft', {
+    _elementSelectorModalClasses: {
+      'CraftCms\\Cms\\Asset\\Elements\\Asset': PluginAssetModal,
+    },
+  });
+
+  const module = await import('./index');
+
+  expect(
+    module.elementSelectorModalClass('CraftCms\\Cms\\Asset\\Elements\\Asset')
+  ).toBe(PluginAssetModal);
 });
diff --git a/resources/js/modules/element-selector-modal/index.ts b/resources/js/modules/element-selector-modal/index.ts
index 3fd0c8c85fb..74a2ce114d1 100644
--- a/resources/js/modules/element-selector-modal/index.ts
+++ b/resources/js/modules/element-selector-modal/index.ts
@@ -3,31 +3,42 @@ import {t} from '@craftcms/ui';
 import {BaseElementSelectorModal} from './base-element-selector-modal';
 import {AssetSelectorModal} from './asset-selector-modal';
 import {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
+import {
+  adoptLegacyRegistrations,
+  createElementSelectorModal,
+  hasElementSelectorModalClass,
+  registerElementSelectorModalClass,
+} from './registry';
 
-declare const Craft: any;
+const ASSET = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
 
 BaseElementSelectorModal.defaults.modalTitle ??= t('Select element');
 BaseElementSelectorModal.defaults.selectBtnLabel ??= t('Select');
 
-// Assign legacy `Craft.*` globals so PHP-emitted `new Craft.BaseElementSelectorModal(...)`
-// and plugin code that calls `Craft.registerElementSelectorModalClass(...)` keep working.
+adoptLegacyRegistrations();
+
+// Skipped when something got there first, so a plugin can replace the built-in
+// asset modal without the duplicate-registration throw.
+if (!hasElementSelectorModalClass(ASSET)) {
+  registerElementSelectorModalClass(ASSET, AssetSelectorModal);
+}
+
+// The classes stay on `Craft` for PHP-emitted boots (`new
+// Craft.VolumeFolderSelectorModal(…)`); the registry functions stay for plugins.
 registerCraftGlobals({
   BaseElementSelectorModal,
   AssetSelectorModal,
   VolumeFolderSelectorModal,
+  createElementSelectorModal,
+  registerElementSelectorModalClass,
 });
 
-if (
-  typeof Craft._elementSelectorModalClasses?.[
-    'CraftCms\\Cms\\Asset\\Elements\\Asset'
-  ] === 'undefined'
-) {
-  Craft.registerElementSelectorModalClass?.(
-    'CraftCms\\Cms\\Asset\\Elements\\Asset',
-    AssetSelectorModal
-  );
-}
-
 export {BaseElementSelectorModal} from './base-element-selector-modal';
 export {AssetSelectorModal} from './asset-selector-modal';
 export {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
+export {
+  createElementSelectorModal,
+  elementSelectorModalClass,
+  registerElementSelectorModalClass,
+  type ElementSelectorModalClass,
+} from './registry';
diff --git a/resources/js/modules/element-selector-modal/registry.test.ts b/resources/js/modules/element-selector-modal/registry.test.ts
new file mode 100644
index 00000000000..5c662ec645f
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/registry.test.ts
@@ -0,0 +1,75 @@
+import {afterEach, beforeEach, expect, it, vi} from 'vite-plus/test';
+import {BaseElementSelectorModal} from './base-element-selector-modal';
+import {
+  adoptLegacyRegistrations,
+  createElementSelectorModal,
+  elementSelectorModalClass,
+  hasElementSelectorModalClass,
+  registerElementSelectorModalClass,
+  resetElementSelectorModalClasses,
+} from './registry';
+
+class FakeModal {
+  constructor(
+    public elementType: string,
+    public settings?: Record<string, any>
+  ) {}
+}
+
+const ENTRY = 'CraftCms\\Cms\\Entry\\Elements\\Entry';
+
+beforeEach(() => resetElementSelectorModalClasses());
+
+afterEach(() => {
+  resetElementSelectorModalClasses();
+  vi.unstubAllGlobals();
+});
+
+it('falls back to the base modal for an unregistered element type', () => {
+  expect(elementSelectorModalClass(ENTRY)).toBe(BaseElementSelectorModal);
+  expect(hasElementSelectorModalClass(ENTRY)).toBe(false);
+});
+
+it('constructs the registered class with the element type and settings', () => {
+  registerElementSelectorModalClass(ENTRY, FakeModal as never);
+
+  const modal = createElementSelectorModal(ENTRY, {modalTitle: 'Choose'});
+
+  expect(modal).toBeInstanceOf(FakeModal);
+  expect((modal as unknown as FakeModal).elementType).toBe(ENTRY);
+  expect((modal as unknown as FakeModal).settings).toEqual({
+    modalTitle: 'Choose',
+  });
+});
+
+it('refuses a second registration for one element type', () => {
+  registerElementSelectorModalClass(ENTRY, FakeModal as never);
+
+  expect(() =>
+    registerElementSelectorModalClass(ENTRY, FakeModal as never)
+  ).toThrow(/already been registered/);
+});
+
+it('adopts classes the legacy bundle registered before it loaded', () => {
+  vi.stubGlobal('Craft', {_elementSelectorModalClasses: {[ENTRY]: FakeModal}});
+
+  adoptLegacyRegistrations();
+
+  expect(elementSelectorModalClass(ENTRY)).toBe(FakeModal);
+});
+
+it('keeps its own registration when the legacy bundle claims the same type', () => {
+  class Newer {}
+  registerElementSelectorModalClass(ENTRY, Newer as never);
+  vi.stubGlobal('Craft', {_elementSelectorModalClasses: {[ENTRY]: FakeModal}});
+
+  adoptLegacyRegistrations();
+
+  expect(elementSelectorModalClass(ENTRY)).toBe(Newer);
+});
+
+it('tolerates the legacy registry being gone', () => {
+  vi.stubGlobal('Craft', {});
+
+  expect(() => adoptLegacyRegistrations()).not.toThrow();
+});
diff --git a/resources/js/modules/element-selector-modal/registry.ts b/resources/js/modules/element-selector-modal/registry.ts
new file mode 100644
index 00000000000..7b340ae2014
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/registry.ts
@@ -0,0 +1,76 @@
+import {BaseElementSelectorModal} from './base-element-selector-modal';
+
+export type ElementSelectorModalClass = new (
+  elementType: string,
+  settings?: Record<string, any>
+) => BaseElementSelectorModal;
+
+const classes = new Map<string, ElementSelectorModalClass>();
+
+/**
+ * Registers the modal class to use for an element type.
+ *
+ * Throws on a second registration for the same type, matching the legacy
+ * registry — two plugins claiming one element type is a conflict to surface,
+ * not to resolve by last-write-wins.
+ */
+export function registerElementSelectorModalClass(
+  elementType: string,
+  modalClass: ElementSelectorModalClass
+): void {
+  if (classes.has(elementType)) {
+    throw new Error(
+      `An element selector modal class has already been registered for the element type “${elementType}”.`
+    );
+  }
+
+  classes.set(elementType, modalClass);
+}
+
+export function hasElementSelectorModalClass(elementType: string): boolean {
+  return classes.has(elementType);
+}
+
+/** The class registered for an element type, or the base modal. */
+export function elementSelectorModalClass(
+  elementType: string
+): ElementSelectorModalClass {
+  return classes.get(elementType) ?? BaseElementSelectorModal;
+}
+
+export function createElementSelectorModal(
+  elementType: string,
+  settings?: Record<string, any>
+): BaseElementSelectorModal {
+  return new (elementSelectorModalClass(elementType))(elementType, settings);
+}
+
+/**
+ * Takes over anything already on the legacy `Craft._elementSelectorModalClasses`
+ * object.
+ *
+ * The legacy bundle is a plain script and runs before this module, so a plugin
+ * can have registered before there was anywhere modern to put it. Existing
+ * entries win over nothing here — a type this module registers itself is left
+ * alone.
+ */
+export function adoptLegacyRegistrations(): void {
+  const legacy = (window as any).Craft?._elementSelectorModalClasses as
+    | Record<string, ElementSelectorModalClass>
+    | undefined;
+
+  if (!legacy) {
+    return;
+  }
+
+  for (const [elementType, modalClass] of Object.entries(legacy)) {
+    if (!classes.has(elementType)) {
+      classes.set(elementType, modalClass);
+    }
+  }
+}
+
+/** Test seam. */
+export function resetElementSelectorModalClasses(): void {
+  classes.clear();
+}
diff --git a/resources/js/modules/link-field/craft-link-field.ts b/resources/js/modules/link-field/craft-link-field.ts
index 9e26ec330b4..a4a1cd4d173 100644
--- a/resources/js/modules/link-field/craft-link-field.ts
+++ b/resources/js/modules/link-field/craft-link-field.ts
@@ -1,4 +1,5 @@
 import {t} from '@craftcms/ui';
+import {createElementSelectorModal} from '@/modules/element-selector-modal/registry';
 import '@craftcms/ui/components/disclosure/disclosure';
 import '@craftcms/ui/components/field-group/field-group';
 import {
@@ -175,7 +176,7 @@ class CraftLinkField extends LitElement {
       event.currentTarget instanceof HTMLElement ? event.currentTarget : null
     );
 
-    const modal = Craft.createElementSelectorModal(type.elementType, {
+    const modal = createElementSelectorModal(type.elementType, {
       ...config,
       closeOtherModals: false,
       hideOnSelect: true,
diff --git a/resources/js/modules/markdown-field/behaviors/assets.ts b/resources/js/modules/markdown-field/behaviors/assets.ts
index 6e7bc6da2fb..9daf72417d6 100644
--- a/resources/js/modules/markdown-field/behaviors/assets.ts
+++ b/resources/js/modules/markdown-field/behaviors/assets.ts
@@ -1,4 +1,5 @@
 import {t} from '@craftcms/ui';
+import {createElementSelectorModal} from '@/modules/element-selector-modal/registry';
 import type {OverType as OverTypeInstance} from 'overtype';
 import type {PreviewController} from './preview';
 import {escapeMarkdownLabel} from './utilities';
@@ -33,24 +34,21 @@ export function createAssetController(
 
   function open(): void {
     if (!assetSelectorModal) {
-      assetSelectorModal = Craft.createElementSelectorModal(
-        ASSET_ELEMENT_TYPE,
-        {
-          closeOtherModals: false,
-          criteria: assetCriteria,
-          hideOnSelect: true,
-          modalTitle: t('Choose an asset'),
-          multiSelect: false,
-          onSelect: (assets: AssetInfo[]) => {
-            const [asset] = assets;
+      assetSelectorModal = createElementSelectorModal(ASSET_ELEMENT_TYPE, {
+        closeOtherModals: false,
+        criteria: assetCriteria,
+        hideOnSelect: true,
+        modalTitle: t('Choose an asset'),
+        multiSelect: false,
+        onSelect: (assets: AssetInfo[]) => {
+          const [asset] = assets;
 
-            if (asset) {
-              insert(asset);
-            }
-          },
-          sources: assetSources,
-        }
-      );
+          if (asset) {
+            insert(asset);
+          }
+        },
+        sources: assetSources,
+      });
 
       return;
     }

From d947747319461e8630a0006d9215625d87e067ed Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 12:57:14 -0500
Subject: [PATCH 05/24] Extract shared element index state resolution
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ContentIndexViewModel (the Inertia payload) and ElementIndexHtml (the
server-rendered shell behind the element-selector modal and the remaining
legacy screens) had grown independent implementations of the same
pre-query decisions: which sources an index lists, which table columns and
sort options are selectable, and whether the site/status menus apply.

ElementIndexState is now the one implementation, and both call it. Source
restriction — previously only in ElementIndexHtml, inline — is exposed as
an explicit `restrictTo` parameter, along with the heading pruning, nested
key recovery and sidebar computation that go with it. Context stays a
first-class parameter so each caller keeps resolving under the context it
always did.

No intended behavior change, with two exceptions that fall out of the
shared implementation always returning a Collection of sources:

- `sources: false` (the deletion-blocker detail panes) fatally errored
  with "Call to a member function every() on array" whenever the site menu
  resolved to true, which it does for any localized element type.
- Restricting to a nested source key that had to be slotted in behind
  another key hit array_splice() with a Collection, a TypeError.

ElementIndexHtml keeps passing `showStatusMenu: 'auto'` straight through
rather than resolving it: the toolbar template treats any truthy value as
"render the menu" and lets the JS index fill in the statuses, so resolving
it server-side would change what renders.
---
 src/Cp/Html/ElementIndexHtml.php              |  94 ++-----
 src/Element/ElementIndexState.php             | 241 ++++++++++++++++++
 src/Http/ViewModels/ContentIndexViewModel.php |  72 ++++--
 tests/Feature/Cp/ElementIndexHtmlTest.php     |  21 ++
 .../Feature/Element/ElementIndexStateTest.php | 236 +++++++++++++++++
 5 files changed, 567 insertions(+), 97 deletions(-)
 create mode 100644 src/Element/ElementIndexState.php
 create mode 100644 tests/Feature/Element/ElementIndexStateTest.php

diff --git a/src/Cp/Html/ElementIndexHtml.php b/src/Cp/Html/ElementIndexHtml.php
index 578035573d2..8ec042faa6a 100644
--- a/src/Cp/Html/ElementIndexHtml.php
+++ b/src/Cp/Html/ElementIndexHtml.php
@@ -5,6 +5,7 @@
 namespace CraftCms\Cms\Cp\Html;
 
 use CraftCms\Cms\Element\Contracts\ElementInterface;
+use CraftCms\Cms\Element\ElementIndexState;
 use CraftCms\Cms\Element\ElementSources;
 use CraftCms\Cms\Site\Sites;
 use CraftCms\Cms\Support\Facades\HtmlStack;
@@ -23,6 +24,7 @@
     public function __construct(
         private Sites $sites,
         private ElementSources $elementSources,
+        private ElementIndexState $indexState,
     ) {}
 
     /**
@@ -48,91 +50,41 @@ public function html(string $elementType, array $config = []): string
             'sources' => null,
         ];
 
+        // Note that 'auto' is deliberately left alone here rather than resolved
+        // via ElementIndexState::showStatusMenu(): the toolbar template treats
+        // any truthy value as "render the menu" and lets the JS index fill in
+        // the statuses, and resolving it server-side would change what renders.
         if ($config['showStatusMenu'] !== 'auto') {
             $config['showStatusMenu'] = (bool) $config['showStatusMenu'];
         }
 
-        $config['showSiteMenu'] = $config['showSiteMenu'] === 'auto'
-            ? $elementType::isLocalized()
-            : (bool) $config['showSiteMenu'];
+        $config['showSiteMenu'] = $this->indexState->showSiteMenu($elementType, $config['showSiteMenu']);
 
         $siteIds = $config['siteIds'] ?? $this->sites->getEditableSiteIds()->all();
 
-        $sortOptions = Collection::make($elementType::sortOptions())
-            ->map(fn ($option, $key) => [
-                'label' => $option['label'] ?? $option,
-                'attr' => $option['attribute'] ?? $option['orderBy'] ?? $key,
-                'defaultDir' => $option['defaultDir'] ?? 'asc',
+        $sortOptions = $this->indexState->sortOptions($elementType)
+            ->map(fn (array $option) => [
+                'label' => $option['label'] ?? $option['option'],
+                'attr' => $option['attribute'] ?? $option['key'],
+                'defaultDir' => $option['defaultDir'],
             ])
-            ->values()
             ->all();
         $sortOptionsKey = 'baseSortOptions';
 
-        $tableColumns = $this->elementSources->getAvailableTableAttributes($elementType)->all();
+        // No source is resolved server-side here — the JS index picks one — so
+        // only the element type's common attributes are offered.
+        $tableColumns = $this->indexState->tableColumns($elementType)->all();
 
         if ($config['sources'] !== false) {
-            if (is_array($config['sources'])) {
-                $indexedSourceKeys = array_flip($config['sources']);
-                $allSources = $this->elementSources->getSources($elementType, $config['context']);
-                $sources = [];
-
-                foreach ($allSources as $source) {
-                    if ($source['type'] === ElementSources::TYPE_HEADING) {
-                        $sources[] = $source;
-                    } elseif (isset($indexedSourceKeys[$source['key']])) {
-                        $sources[] = $source;
-                        // Unset so we can keep track of which keys couldn't be found
-                        unset($indexedSourceKeys[$source['key']]);
-                    }
-                }
-
-                $sources = ElementSources::filterExtraHeadings($sources);
-
-                // Did we miss any source keys? (This could happen if some are nested)
-                if (! empty($indexedSourceKeys)) {
-                    foreach (array_keys($indexedSourceKeys) as $key) {
-                        $source = $this->elementSources->findSource($elementType, $key, $config['context']);
-                        if ($source !== null) {
-                            // If it was listed after another source key that made it in, insert it there
-                            $pos = array_search($key, $config['sources']);
-                            $inserted = false;
-                            if ($pos > 0) {
-                                $prevKey = $config['sources'][$pos - 1];
-                                foreach ($sources as $i => $otherSource) {
-                                    if (($otherSource['key'] ?? null) === $prevKey) {
-                                        array_splice($sources, $i + 1, 0, [$source]);
-                                        $inserted = true;
-                                        break;
-                                    }
-                                }
-                            }
-                            if (! $inserted) {
-                                $sources[] = $source;
-                            }
-                        }
-                    }
-                }
-            } else {
-                $sources = $this->elementSources->getSources($elementType, $config['context']);
-            }
-
-            // Show the sidebar if there are at least two (non-heading) sources
-            $showSidebar = (function () use ($sources): bool {
-                $foundSource = false;
-                foreach ($sources as $source) {
-                    if ($source['type'] !== ElementSources::TYPE_HEADING) {
-                        if ($foundSource || ! empty($source['nested'])) {
-                            return true;
-                        }
-                        $foundSource = true;
-                    }
-                }
-
-                return false;
-            })();
+            $sources = $this->indexState->sources(
+                $elementType,
+                $config['context'],
+                restrictTo: is_array($config['sources']) ? $config['sources'] : null,
+            );
+            $showSidebar = $this->indexState->showSidebar($sources);
         } else {
             $showSidebar = false;
-            $sources = [
+            $sources = Collection::make([
                 [
                     'type' => ElementSources::TYPE_NATIVE,
                     'key' => '__IMP__',
@@ -142,7 +94,7 @@ public function html(string $elementType, array $config = []): string
                     'defaultViewMode' => $config['defaultViewMode'],
                     'fieldLayouts' => $config['fieldLayouts'],
                 ],
-            ];
+            ]);
 
             // if field layouts were supplied, merge in additional table columns and sort columns
             if (! empty($config['fieldLayouts'])) {
diff --git a/src/Element/ElementIndexState.php b/src/Element/ElementIndexState.php
new file mode 100644
index 00000000000..ec6607b7a94
--- /dev/null
+++ b/src/Element/ElementIndexState.php
@@ -0,0 +1,241 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Element;
+
+use CraftCms\Cms\Cp\Html\ElementIndexHtml;
+use CraftCms\Cms\Element\Contracts\ElementInterface;
+use CraftCms\Cms\Http\ViewModels\ContentIndexViewModel;
+use CraftCms\Cms\Site\Sites;
+use Illuminate\Container\Attributes\Scoped;
+use Illuminate\Support\Collection;
+
+/**
+ * Resolves the server-side state of an element index — the parts of an index
+ * screen that are decided before any elements are queried: which sources it
+ * lists, which table columns and sort options are selectable, and whether the
+ * site/status menus apply.
+ *
+ * This is the single implementation shared by the Inertia payload
+ * ({@see ContentIndexViewModel}) and the server-rendered index shell
+ * ({@see ElementIndexHtml}, used by the element-selector modal and the
+ * remaining legacy screens), which had grown independent copies of all of it.
+ *
+ * Query building is {@see ElementIndexes}' job; this class never touches a
+ * query.
+ *
+ * @phpstan-import-type SourceConfig from ElementSources
+ *
+ * @phpstan-type NormalizedSortOption array{
+ *     key: array-key,
+ *     label: mixed,
+ *     attribute: mixed,
+ *     defaultDir: mixed,
+ *     option: mixed,
+ * }
+ */
+#[Scoped]
+readonly class ElementIndexState
+{
+    public function __construct(
+        private ElementSources $elementSources,
+    ) {}
+
+    /**
+     * The index's sources, optionally restricted to a given set of source keys.
+     *
+     * `$restrictTo` is how the element-selector modal narrows an index down to
+     * the sources a field is configured for: headings are kept (then pruned
+     * back down if they end up empty), and any requested key that isn't a
+     * top-level source is looked up individually and slotted in behind the key
+     * it was listed after.
+     *
+     * @param  class-string<ElementInterface>  $elementType
+     * @param  string[]|null  $restrictTo  Source keys to limit the list to, or `null` for every source
+     * @return Collection<int, SourceConfig>
+     */
+    public function sources(
+        string $elementType,
+        string $context = ElementSources::CONTEXT_INDEX,
+        bool $withDisabled = false,
+        ?string $page = null,
+        ?array $restrictTo = null,
+    ): Collection {
+        $allSources = $this->elementSources->getSources($elementType, $context, $withDisabled, $page);
+
+        if ($restrictTo === null) {
+            return $allSources;
+        }
+
+        $restrictTo = array_values($restrictTo);
+        // Flipped so found keys can be unset, leaving the ones we couldn't place
+        $missingKeys = array_flip($restrictTo);
+        $sources = [];
+
+        foreach ($allSources as $source) {
+            if ($source['type'] === ElementSources::TYPE_HEADING) {
+                $sources[] = $source;
+            } elseif (isset($missingKeys[$source['key']])) {
+                $sources[] = $source;
+                unset($missingKeys[$source['key']]);
+            }
+        }
+
+        $sources = ElementSources::filterExtraHeadings($sources)->all();
+
+        // Whatever's left is probably a nested source, which getSources() doesn't
+        // surface at the top level.
+        foreach (array_keys($missingKeys) as $key) {
+            $source = $this->elementSources->findSource($elementType, (string) $key, $context, $withDisabled, $page);
+
+            if ($source === null) {
+                continue;
+            }
+
+            $inserted = false;
+            // If it was listed after another source key that made it in, insert it there
+            $pos = array_search($key, $restrictTo);
+
+            if ($pos > 0) {
+                $prevKey = $restrictTo[$pos - 1];
+
+                foreach ($sources as $i => $otherSource) {
+                    if (($otherSource['key'] ?? null) === $prevKey) {
+                        array_splice($sources, $i + 1, 0, [$source]);
+                        $inserted = true;
+                        break;
+                    }
+                }
+            }
+
+            if (! $inserted) {
+                $sources[] = $source;
+            }
+        }
+
+        return collect($sources);
+    }
+
+    /**
+     * Whether the sidebar is worth showing: there are at least two selectable
+     * (non-heading) sources, or a single one with nested sources under it.
+     *
+     * @param  iterable<int, SourceConfig>  $sources
+     */
+    public function showSidebar(iterable $sources): bool
+    {
+        $foundSource = false;
+
+        foreach ($sources as $source) {
+            if ($source['type'] !== ElementSources::TYPE_HEADING) {
+                if ($foundSource || ! empty($source['nested'])) {
+                    return true;
+                }
+
+                $foundSource = true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * The table columns a user can choose from, keyed by attribute name: the
+     * element type's common attributes, plus the given source's own columns
+     * when one is known. (The index shell resolves its source client-side, so
+     * it only gets the common set.)
+     *
+     * @param  class-string<ElementInterface>  $elementType
+     * @return Collection<string, array<string, mixed>>
+     */
+    public function tableColumns(string $elementType, ?string $sourceKey = null): Collection
+    {
+        $columns = $this->elementSources->getAvailableTableAttributes($elementType);
+
+        if ($sourceKey !== null) {
+            $columns = $columns->merge($this->elementSources->getSourceTableAttributes($elementType, $sourceKey));
+        }
+
+        return $columns;
+    }
+
+    /**
+     * The element type's sort options, normalized.
+     *
+     * @param  class-string<ElementInterface>  $elementType
+     * @return Collection<int, NormalizedSortOption>
+     */
+    public function sortOptions(string $elementType): Collection
+    {
+        return collect($elementType::sortOptions())
+            ->map(fn (mixed $option, string|int $key): array => $this->normalizeSortOption($option, $key))
+            ->values();
+    }
+
+    /**
+     * Normalizes one sort option into `key`/`label`/`attribute`/`defaultDir`.
+     *
+     * A sort option is either a bare label (keyed by the attribute it sorts on)
+     * or an array with some combination of `label`, `attribute`, `orderBy` and
+     * `defaultDir`. `attribute` is left as-is when it resolves to an `orderBy`
+     * that isn't a string — a query expression or closure sorts fine but can't
+     * be addressed from the client, so callers that need an addressable name
+     * filter on `is_string()`.
+     *
+     * `label` is only set when the option declares one; the raw `option` comes
+     * along so callers can keep their own fallback.
+     *
+     * @return NormalizedSortOption
+     */
+    public function normalizeSortOption(mixed $option, string|int $key = ''): array
+    {
+        if (! is_array($option)) {
+            return [
+                'key' => $key,
+                'label' => $option,
+                'attribute' => (string) $key,
+                'defaultDir' => 'asc',
+                'option' => $option,
+            ];
+        }
+
+        return [
+            'key' => $key,
+            'label' => $option['label'] ?? null,
+            'attribute' => $option['attribute'] ?? $option['orderBy'] ?? null,
+            'defaultDir' => $option['defaultDir'] ?? 'asc',
+            'option' => $option,
+        ];
+    }
+
+    /**
+     * Resolves a `showSiteMenu` setting, where `'auto'` means "show it if the
+     * element type is localized".
+     *
+     * Callers that only ever offer the menu on multi-site installs gate this
+     * behind {@see Sites::isMultiSite()} themselves.
+     *
+     * @param  class-string<ElementInterface>  $elementType
+     */
+    public function showSiteMenu(string $elementType, mixed $setting = 'auto'): bool
+    {
+        return $setting === 'auto'
+            ? $elementType::isLocalized()
+            : (bool) $setting;
+    }
+
+    /**
+     * Resolves a `showStatusMenu` setting, where `'auto'` means "show it if the
+     * element type has statuses worth filtering on" — a single status is no
+     * choice at all, and status filtering is a no-op for types without any.
+     *
+     * @param  class-string<ElementInterface>  $elementType
+     */
+    public function showStatusMenu(string $elementType, mixed $setting = 'auto'): bool
+    {
+        return $setting === 'auto'
+            ? ($elementType::hasStatuses() && count($elementType::statuses()) >= 2)
+            : (bool) $setting;
+    }
+}
diff --git a/src/Http/ViewModels/ContentIndexViewModel.php b/src/Http/ViewModels/ContentIndexViewModel.php
index b3e27ba87a6..a4f9b4da27f 100644
--- a/src/Http/ViewModels/ContentIndexViewModel.php
+++ b/src/Http/ViewModels/ContentIndexViewModel.php
@@ -8,6 +8,7 @@
 use CraftCms\Cms\Cp\Html\ElementHtml;
 use CraftCms\Cms\Element\Contracts\ElementInterface;
 use CraftCms\Cms\Element\ElementIndexes;
+use CraftCms\Cms\Element\ElementIndexState;
 use CraftCms\Cms\Element\Enums\ElementIndexViewMode;
 use CraftCms\Cms\Element\Queries\Contracts\ElementQueryInterface;
 use CraftCms\Cms\Http\Requests\ElementIndexRequest;
@@ -182,13 +183,15 @@ public function statusOptions(): array
 
     public function showStatusMenu(): bool
     {
-        return $this->elementType::hasStatuses()
-            && count($this->elementType::statuses()) >= 2;
+        return $this->indexState()->showStatusMenu($this->elementType);
     }
 
     public function showSiteMenu(): bool
     {
-        return Sites::isMultiSite() && $this->elementType::isLocalized();
+        // The shared resolution is just "is the element type localized?"; the
+        // Inertia index additionally only ever offers the menu on multi-site
+        // installs, where there's something to switch between.
+        return Sites::isMultiSite() && $this->indexState()->showSiteMenu($this->elementType);
     }
 
     /**
@@ -211,7 +214,10 @@ public function title(): string
     /** @return list<array<string, mixed>> */
     public function sources(): array
     {
-        return $this->resolvedSources ??= ElementSources::getSources(
+        // The context is deliberately left at ElementSources' `index` default,
+        // which is what this method has always resolved under. (sourceState()
+        // passes static::RENDER_CONTEXT explicitly — the same value today.)
+        return $this->resolvedSources ??= $this->indexState()->sources(
             $this->elementType,
             withDisabled: true,
             page: $this->page,
@@ -272,40 +278,32 @@ public function sortOptions(): array
             return [];
         }
 
+        $indexState = $this->indexState();
         $options = [];
 
-        foreach ($this->elementType::sortOptions() as $attribute => $option) {
-            if (! is_array($option)) {
-                $options[$attribute] = [
-                    'label' => $option,
-                    'value' => $attribute,
-                    'defaultDir' => 'asc',
-                ];
-
-                continue;
-            }
-
-            $value = $option['attribute']
-                ?? (is_string($option['orderBy'] ?? null) ? $option['orderBy'] : null);
+        foreach ($indexState->sortOptions($this->elementType) as $option) {
+            $value = self::addressableSortAttribute($option);
 
-            if (is_string($value) && $value !== '') {
+            if ($value !== null) {
                 $options[$value] = [
                     'label' => $option['label'] ?? $value,
                     'value' => $value,
-                    'defaultDir' => $option['defaultDir'] ?? 'asc',
+                    'defaultDir' => $option['defaultDir'],
                 ];
             }
         }
 
-        foreach (ElementSources::getSourceSortOptions($this->elementType, $sourceKey) as $option) {
-            $value = $option['attribute']
-                ?? (is_string($option['orderBy'] ?? null) ? $option['orderBy'] : null);
+        // The element type's own options win over a source's field-layout
+        // options that happen to sort on the same attribute.
+        foreach (ElementSources::getSourceSortOptions($this->elementType, $sourceKey) as $key => $option) {
+            $option = $indexState->normalizeSortOption($option, $key);
+            $value = self::addressableSortAttribute($option);
 
-            if (is_string($value) && $value !== '' && ! isset($options[$value])) {
+            if ($value !== null && ! isset($options[$value])) {
                 $options[$value] = [
                     'label' => $option['label'] ?? $value,
                     'value' => $value,
-                    'defaultDir' => $option['defaultDir'] ?? 'asc',
+                    'defaultDir' => $option['defaultDir'],
                 ];
             }
         }
@@ -326,8 +324,8 @@ public function tableColumns(): array
             return [];
         }
 
-        return ElementSources::getAvailableTableAttributes($this->elementType)
-            ->merge(ElementSources::getSourceTableAttributes($this->elementType, $sourceKey))
+        return $this->indexState()
+            ->tableColumns($this->elementType, $sourceKey)
             ->map(fn (array $attribute, string $key) => [
                 'label' => $attribute['label'],
                 'value' => $key,
@@ -494,6 +492,28 @@ protected function sourceState(): array
         return $this->resolvedSource = $resolved;
     }
 
+    /**
+     * The shared server-side index state — source, column, sort-option and
+     * menu resolution, shared with the server-rendered index shell.
+     */
+    private function indexState(): ElementIndexState
+    {
+        return app(ElementIndexState::class);
+    }
+
+    /**
+     * The client addresses sort options by attribute name, so options that only
+     * sort by a query expression or closure aren't offered.
+     *
+     * @param  array{attribute: mixed, ...}  $option
+     */
+    private static function addressableSortAttribute(array $option): ?string
+    {
+        $attribute = $option['attribute'];
+
+        return is_string($attribute) && $attribute !== '' ? $attribute : null;
+    }
+
     /**
      * The view mode: sent as a string when the user switches views (see the
      * `useElementIndexViewMode` composable), falling back to the persisted
diff --git a/tests/Feature/Cp/ElementIndexHtmlTest.php b/tests/Feature/Cp/ElementIndexHtmlTest.php
index 781ea8c3461..0b27bc0e7dd 100644
--- a/tests/Feature/Cp/ElementIndexHtmlTest.php
+++ b/tests/Feature/Cp/ElementIndexHtmlTest.php
@@ -25,6 +25,27 @@
         ->and($html)->toContain('class="elements"');
 });
 
+it('renders a sidebar-less index when sources are disabled', function () {
+    // The site menu resolves to `true` here (entries are localized), which used
+    // to take the site-ID filtering path with a plain array of sources.
+    $html = app(ElementIndexHtml::class)->html(Entry::class, [
+        'sources' => false,
+        'registerJs' => false,
+    ]);
+
+    expect($html)->toContain('class="sidebar hidden"')
+        ->and($html)->toContain('__IMP__');
+});
+
+it('restricts the source list to the given source keys', function () {
+    $html = app(ElementIndexHtml::class)->html(Entry::class, [
+        'sources' => ['*'],
+        'registerJs' => false,
+    ]);
+
+    expect($html)->toContain('data-key="*"');
+});
+
 it('includes footer in administrative contexts and omits it otherwise', function () {
     $indexHtml = app(ElementIndexHtml::class)->html(Entry::class, [
         'context' => 'index',
diff --git a/tests/Feature/Element/ElementIndexStateTest.php b/tests/Feature/Element/ElementIndexStateTest.php
new file mode 100644
index 00000000000..822737232d9
--- /dev/null
+++ b/tests/Feature/Element/ElementIndexStateTest.php
@@ -0,0 +1,236 @@
+<?php
+
+declare(strict_types=1);
+
+use CraftCms\Cms\Element\ElementIndexState;
+use CraftCms\Cms\Element\ElementSources;
+use CraftCms\Cms\Entry\Elements\Entry;
+use CraftCms\Cms\ProjectConfig\ProjectConfig;
+use CraftCms\Cms\User\Elements\User;
+
+beforeEach(function () {
+    $this->indexState = app(ElementIndexState::class);
+});
+
+/**
+ * Sets up entry sources as: `*`, a "Custom" heading, `custom:a`, `custom:b`
+ * (with a nested `custom:b-child`), `custom:c`, and a trailing empty heading.
+ */
+function setUpRestrictableEntrySources(): void
+{
+    app(ProjectConfig::class)->set(sprintf('%s.%s', ProjectConfig::PATH_ELEMENT_SOURCES, Entry::class), [
+        [
+            'type' => ElementSources::TYPE_NATIVE,
+            'key' => '*',
+        ],
+        [
+            'type' => ElementSources::TYPE_HEADING,
+            'heading' => 'Custom',
+        ],
+        [
+            'type' => ElementSources::TYPE_CUSTOM,
+            'key' => 'custom:a',
+            'label' => 'A',
+        ],
+        [
+            'type' => ElementSources::TYPE_CUSTOM,
+            'key' => 'custom:b',
+            'label' => 'B',
+            'nested' => [
+                [
+                    'type' => ElementSources::TYPE_CUSTOM,
+                    'key' => 'custom:b-child',
+                    'label' => 'B child',
+                ],
+            ],
+        ],
+        [
+            'type' => ElementSources::TYPE_CUSTOM,
+            'key' => 'custom:c',
+            'label' => 'C',
+        ],
+        [
+            'type' => ElementSources::TYPE_HEADING,
+            'heading' => 'Trailing',
+        ],
+    ]);
+}
+
+/** @param iterable<int, array<string, mixed>> $sources */
+function sourceKeys(iterable $sources): array
+{
+    $keys = [];
+
+    foreach ($sources as $source) {
+        $keys[] = $source['type'] === ElementSources::TYPE_HEADING
+            ? sprintf('heading:%s', $source['heading'] ?? '')
+            : $source['key'];
+    }
+
+    return $keys;
+}
+
+it('returns every source when not restricted', function () {
+    setUpRestrictableEntrySources();
+
+    expect(sourceKeys($this->indexState->sources(Entry::class, ElementSources::CONTEXT_MODAL)))
+        ->toBe(['*', 'heading:Custom', 'custom:a', 'custom:b', 'custom:c', 'heading:Trailing']);
+});
+
+it('restricts sources to the given keys, in source order', function () {
+    setUpRestrictableEntrySources();
+
+    // Requested out of order — the source list's own order wins.
+    $sources = $this->indexState->sources(
+        Entry::class,
+        ElementSources::CONTEXT_MODAL,
+        restrictTo: ['custom:c', 'custom:a'],
+    );
+
+    expect(sourceKeys($sources))->toBe(['heading:Custom', 'custom:a', 'custom:c']);
+});
+
+it('drops headings left with no sources under them when restricting', function () {
+    setUpRestrictableEntrySources();
+
+    // `*` sits above the "Custom" heading, so that heading is left empty and
+    // pruned, as is the always-trailing one.
+    $sources = $this->indexState->sources(
+        Entry::class,
+        ElementSources::CONTEXT_MODAL,
+        restrictTo: ['*'],
+    );
+
+    expect(sourceKeys($sources))->toBe(['*']);
+});
+
+it('pulls in restricted source keys that are nested, after the key they follow', function () {
+    setUpRestrictableEntrySources();
+
+    $sources = $this->indexState->sources(
+        Entry::class,
+        ElementSources::CONTEXT_MODAL,
+        restrictTo: ['custom:a', 'custom:b/custom:b-child', 'custom:c'],
+    );
+
+    expect(sourceKeys($sources))->toBe(['heading:Custom', 'custom:a', 'custom:b-child', 'custom:c']);
+});
+
+it('appends a nested source key when the key it follows was not included', function () {
+    setUpRestrictableEntrySources();
+
+    $sources = $this->indexState->sources(
+        Entry::class,
+        ElementSources::CONTEXT_MODAL,
+        restrictTo: ['custom:b/custom:b-child', 'custom:c'],
+    );
+
+    expect(sourceKeys($sources))->toBe(['heading:Custom', 'custom:c', 'custom:b-child']);
+});
+
+it('ignores restricted source keys that do not exist', function () {
+    setUpRestrictableEntrySources();
+
+    $sources = $this->indexState->sources(
+        Entry::class,
+        ElementSources::CONTEXT_MODAL,
+        restrictTo: ['custom:a', 'nope'],
+    );
+
+    expect(sourceKeys($sources))->toBe(['heading:Custom', 'custom:a']);
+});
+
+it('returns an empty source list when nothing matches the restriction', function () {
+    setUpRestrictableEntrySources();
+
+    $sources = $this->indexState->sources(
+        Entry::class,
+        ElementSources::CONTEXT_MODAL,
+        restrictTo: ['nope'],
+    );
+
+    expect($sources->all())->toBe([]);
+});
+
+it('shows the sidebar only when there is a real choice of sources', function () {
+    $heading = ['type' => ElementSources::TYPE_HEADING, 'heading' => 'Heading'];
+    $source = fn (string $key, array $extra = []) => ['type' => ElementSources::TYPE_NATIVE, 'key' => $key] + $extra;
+
+    expect($this->indexState->showSidebar([]))->toBeFalse()
+        ->and($this->indexState->showSidebar([$heading]))->toBeFalse()
+        ->and($this->indexState->showSidebar([$heading, $source('a')]))->toBeFalse()
+        ->and($this->indexState->showSidebar([$source('a'), $source('b')]))->toBeTrue()
+        ->and($this->indexState->showSidebar([$source('a', ['nested' => [$source('b')]])]))->toBeTrue()
+        ->and($this->indexState->showSidebar([$source('a', ['nested' => []])]))->toBeFalse();
+});
+
+it('normalizes a bare label sort option against its key', function () {
+    expect($this->indexState->normalizeSortOption('Title', 'title'))->toBe([
+        'key' => 'title',
+        'label' => 'Title',
+        'attribute' => 'title',
+        'defaultDir' => 'asc',
+        'option' => 'Title',
+    ]);
+});
+
+it('normalizes an array sort option, falling back from attribute to orderBy', function () {
+    $withAttribute = ['label' => 'Title', 'attribute' => 'title', 'orderBy' => 'content.title', 'defaultDir' => 'desc'];
+    $withOrderBy = ['label' => 'Slug', 'orderBy' => 'slug'];
+
+    expect($this->indexState->normalizeSortOption($withAttribute, 'title'))
+        ->toBe([
+            'key' => 'title',
+            'label' => 'Title',
+            'attribute' => 'title',
+            'defaultDir' => 'desc',
+            'option' => $withAttribute,
+        ])
+        ->and($this->indexState->normalizeSortOption($withOrderBy, 'slug'))
+        ->toBe([
+            'key' => 'slug',
+            'label' => 'Slug',
+            'attribute' => 'slug',
+            'defaultDir' => 'asc',
+            'option' => $withOrderBy,
+        ]);
+});
+
+it('leaves a non-string orderBy in place so callers can filter it out', function () {
+    $expression = new stdClass;
+    $option = ['label' => 'Structure', 'orderBy' => $expression];
+
+    $normalized = $this->indexState->normalizeSortOption($option, 'structure');
+
+    expect($normalized['attribute'])->toBe($expression)
+        ->and($normalized['label'])->toBe('Structure');
+});
+
+it('normalizes an element type sort options into a list', function () {
+    $options = $this->indexState->sortOptions(Entry::class);
+
+    expect($options->keys()->all())->toBe(range(0, $options->count() - 1))
+        ->and($options->firstWhere('attribute', 'id'))->not->toBeNull()
+        ->and($options->firstWhere('attribute', 'id')['label'])->toBe('ID');
+});
+
+it('merges a source’s table columns in only when a source key is given', function () {
+    $common = $this->indexState->tableColumns(Entry::class);
+    $forSource = $this->indexState->tableColumns(Entry::class, '*');
+
+    expect($common->all())->toBe(app(ElementSources::class)->getAvailableTableAttributes(Entry::class)->all())
+        ->and($forSource->keys()->all())->toContain(...$common->keys()->all());
+});
+
+it('resolves the site menu setting', function () {
+    expect($this->indexState->showSiteMenu(Entry::class))->toBe(Entry::isLocalized())
+        ->and($this->indexState->showSiteMenu(User::class))->toBe(User::isLocalized())
+        ->and($this->indexState->showSiteMenu(Entry::class, false))->toBeFalse()
+        ->and($this->indexState->showSiteMenu(User::class, '1'))->toBeTrue();
+});
+
+it('resolves the status menu setting', function () {
+    expect($this->indexState->showStatusMenu(Entry::class))->toBeTrue()
+        ->and($this->indexState->showStatusMenu(Entry::class, false))->toBeFalse()
+        ->and($this->indexState->showStatusMenu(Entry::class, '0'))->toBeFalse();
+});

From d270dc744ee7d130fd526b46b2d9c68a9200e538 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 13:41:35 -0500
Subject: [PATCH 06/24] Build the element selector modal's chrome with Lit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The modal assembled its own DOM with jQuery — `$('<div/>', {…}).appendTo()`
chains plus `Craft.ui.createButton`/`createSubmitButton` — which meant its
markup was only readable by executing it.

The chrome is now two Lit templates: `chromeTemplate()` for the shell and the
footer buttons, and the sidebar toggle view's header pair. The `$`-prefixed
fields keep handing back jQuery objects, captured with Lit's `ref` directive,
because subclasses and the element select input manipulate them.

The button markup is reproduced rather than delegated, so the `btn submit`
classes, the `.label` inside its `.inline-flex` wrapper and the absolutely
positioned spinner all survive — the CP stylesheet selects on each. Tests now
pin that markup, and no longer stub `Craft.ui` at all.

The sidebar headers render detached and are moved into place: the element
index owns those containers, and `render()` claims whatever it renders into.

One behavior difference: the main heading interpolated the active source name
into an HTML string, so a name containing markup was parsed as HTML. As a Lit
text binding it is escaped.
---
 .../base-element-selector-modal.test.ts       |  82 +++++++-
 .../base-element-selector-modal.ts            | 181 +++++++++++-------
 2 files changed, 195 insertions(+), 68 deletions(-)

diff --git a/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts b/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts
index d8f0ae7037c..4da53e0f163 100644
--- a/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts
+++ b/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts
@@ -14,11 +14,10 @@ it('retains inherited modal settings during initialization', () => {
   trigger.focus();
 
   vi.stubGlobal('$', $);
+  // No `Craft.ui`: the chrome is built from Lit templates now, so nothing here
+  // reaches for the legacy jQuery button factories.
   vi.stubGlobal('Craft', {
     t: (_category: string, message: string) => message,
-    ui: {
-      createSubmitButton: () => $('<button/>'),
-    },
   });
 
   class TestModal extends BaseElementSelectorModal {
@@ -36,6 +35,83 @@ it('retains inherited modal settings during initialization', () => {
   modal.destroy();
 });
 
+function mountModal(settings: Record<string, any> = {}) {
+  vi.stubGlobal('$', $);
+  vi.stubGlobal('Craft', {
+    t: (_category: string, message: string) => message,
+  });
+
+  class TestModal extends BaseElementSelectorModal {
+    override show(): void {}
+  }
+
+  const modal = new TestModal('test');
+  modal.init('test', settings);
+
+  return {
+    modal,
+    container: document.querySelector<HTMLElement>(
+      '.modal.elementselectormodal'
+    )!,
+  };
+}
+
+it('renders the chrome the CP stylesheet expects', () => {
+  const {modal, container} = mountModal({
+    modalTitle: 'Choose an asset',
+    selectBtnLabel: 'Select',
+    showTitle: true,
+  });
+
+  const heading = container.querySelector('h1')!;
+  expect(heading.textContent).toBe('Choose an asset');
+  expect(container.getAttribute('aria-labelledby')).toBe(heading.id);
+  expect(heading.parentElement!.className).toBe('header');
+
+  expect(container.querySelector('.body > .spinner.big')).not.toBeNull();
+  expect(
+    container.querySelector('.footer > .buttons.left.secondary-buttons')
+  ).not.toBeNull();
+  expect(container.querySelector('.footer > .buttons.right')).not.toBeNull();
+
+  const cancelBtn = container.querySelector<HTMLButtonElement>(
+    'button[type="button"]'
+  )!;
+  expect(cancelBtn.className).toBe('btn');
+  expect(cancelBtn.textContent!.trim()).toBe('Cancel');
+
+  // Reproduces `Craft.ui.createSubmitButton({class: 'disabled', spinner: true})`
+  // — the CP stylesheet selects on every part of this.
+  const selectBtn = container.querySelector<HTMLButtonElement>(
+    'button[type="submit"]'
+  )!;
+  expect(selectBtn.className).toBe('btn disabled submit');
+  expect(selectBtn.getAttribute('aria-disabled')).toBe('true');
+  expect(
+    selectBtn.querySelector('.inline-flex.gap-xs > .label')!.textContent!.trim()
+  ).toBe('Select');
+  expect(selectBtn.querySelector('.spinner.spinner-absolute')).not.toBeNull();
+
+  // The `$`-prefixed fields stay jQuery wrappers around those same nodes,
+  // because subclasses and the element select input manipulate them.
+  expect(modal.$selectBtn[0]).toBe(selectBtn);
+  expect(modal.$cancelBtn[0]).toBe(cancelBtn);
+  expect(modal.$body[0]).toBe(container.querySelector('.body'));
+  expect(modal.$footer[0]).toBe(container.querySelector('.footer'));
+
+  modal.destroy();
+});
+
+it('hides the heading unless showTitle is set', () => {
+  const {modal, container} = mountModal({modalTitle: 'Choose'});
+
+  expect(container.querySelector('h1')!.parentElement!.className).toBe(
+    'visually-hidden'
+  );
+
+  modal.destroy();
+});
+
 it('preserves legacy Craft class extension', () => {
   vi.stubGlobal('Craft', {});
   registerCraftGlobals({BaseElementSelectorModal});
diff --git a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
index 0f63127a524..12d5eb7d672 100644
--- a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
@@ -5,6 +5,8 @@ import {
   bod,
   type ModalSettings,
 } from '@craftcms/garnish';
+import {html, render, type TemplateResult} from 'lit';
+import {ref} from 'lit/directives/ref.js';
 import {uiLayerManager} from '@/modules/slideout/slideout';
 
 declare const Craft: any;
@@ -56,6 +58,10 @@ const BASE_DEFAULTS = {
  * modern `@craftcms/garnish` `Modal`. Loads an element index into a modal via a
  * server action, then lets the user select elements and fires `onSelect`.
  *
+ * Its own chrome is built with Lit templates (`chromeTemplate()`,
+ * `buildSidebarToggleView()`); the `$`-prefixed fields are jQuery wrappers around
+ * those nodes, since subclasses and the element select input manipulate them.
+ *
  * The modal shell is modern (`extends Modal`), but element-index interaction
  * retains the jQuery seam: the still-legacy `Craft.createElementIndex` produces
  * jQuery-based DOM, and the `doubletap` / activate events on that DOM are jQuery
@@ -132,52 +138,21 @@ export class BaseElementSelectorModal extends Modal {
     const headingId =
       'elementSelectorModalHeading-' + Math.floor(Math.random() * 1000000);
 
-    const $container = $('<div/>', {
-      class: 'modal elementselectormodal',
-      'aria-labelledby': headingId,
-    }).appendTo($(bod));
-
-    const $headingContainer = $('<div/>', {
-      class: this.settings.showTitle ? 'header' : 'visually-hidden',
-    }).appendTo($container);
-    $('<h1/>', {id: headingId, text: this.settings.modalTitle}).appendTo(
-      $headingContainer
-    );
-
-    this.$body = $('<div/>', {class: 'body'})
-      .append($('<div/>', {class: 'spinner big'}))
-      .appendTo($container);
-
-    this.$footer = $('<div/>', {class: 'footer'}).appendTo($container);
+    // The container is created by hand rather than by the template: `render()`
+    // owns its container's children, and `setContainer()` needs an element that
+    // outlives the render.
+    const container = document.createElement('div');
+    container.className = 'modal elementselectormodal';
+    container.setAttribute('aria-labelledby', headingId);
 
     if (this.settings.fullscreen) {
-      $container.addClass('fullscreen');
+      container.classList.add('fullscreen');
       this.settings.minGutter = 0;
     }
 
-    this.setContainer($container[0]);
-
-    this.$secondaryButtons = $(
-      '<div class="buttons left secondary-buttons"/>'
-    ).appendTo(this.$footer);
-    this.$primaryButtons = $('<div class="buttons right"/>').appendTo(
-      this.$footer
-    );
-
-    this.$cancelBtn = $('<button/>', {
-      type: 'button',
-      class: 'btn',
-      text: Craft.t('app', 'Cancel'),
-    }).appendTo(this.$primaryButtons);
-
-    this.$selectBtn = Craft.ui
-      .createSubmitButton({
-        class: 'disabled',
-        label: this.settings.selectBtnLabel,
-        spinner: true,
-      })
-      .attr('aria-disabled', 'true')
-      .appendTo(this.$primaryButtons);
+    render(this.chromeTemplate(headingId), container);
+    bod.append(container);
+    this.setContainer(container);
 
     // Use native click — <button> fires click on keyboard activation natively.
     this.addListener(this.$cancelBtn[0], 'click', () => this.cancel());
@@ -186,6 +161,73 @@ export class BaseElementSelectorModal extends Modal {
     this.show();
   }
 
+  /**
+   * The modal's own chrome — heading, body, footer and the two footer buttons.
+   *
+   * The `$`-prefixed fields stay jQuery objects: subclasses and the element
+   * select input reach for them (`$primaryButtons.append(…)`,
+   * `$selectBtn.addClass('loading')`), so only their construction moves here.
+   *
+   * The select button reproduces what `Craft.ui.createSubmitButton()` emits —
+   * `btn submit`, a `.label` inside an `.inline-flex` wrapper, and an absolutely
+   * positioned spinner — because the CP stylesheet selects on all three.
+   */
+  protected chromeTemplate(headingId: string): TemplateResult {
+    return html`
+      <div class=${this.settings.showTitle ? 'header' : 'visually-hidden'}>
+        <h1 id=${headingId}>${this.settings.modalTitle}</h1>
+      </div>
+      <div class="body" ${ref((el) => (this.$body = $(el)))}>
+        <div class="spinner big"></div>
+      </div>
+      <div class="footer" ${ref((el) => (this.$footer = $(el)))}>
+        <div
+          class="buttons left secondary-buttons"
+          ${ref((el) => (this.$secondaryButtons = $(el)))}
+        ></div>
+        <div
+          class="buttons right"
+          ${ref((el) => (this.$primaryButtons = $(el)))}
+        >
+          <button
+            type="button"
+            class="btn"
+            ${ref((el) => (this.$cancelBtn = $(el)))}
+          >
+            ${Craft.t('app', 'Cancel')}
+          </button>
+          <button
+            type="submit"
+            class="btn disabled submit"
+            aria-disabled="true"
+            ${ref((el) => (this.$selectBtn = $(el)))}
+          >
+            <div class="inline-flex gap-xs">
+              <div class="label">${this.settings.selectBtnLabel}</div>
+            </div>
+            <div class="spinner spinner-absolute"></div>
+          </button>
+        </div>
+      </div>
+    `;
+  }
+
+  /**
+   * Renders a template and hands back its root element, detached.
+   *
+   * For markup that has to be inserted into DOM this class doesn't own — the
+   * element index's sidebar and main column, which the legacy index renders.
+   * `render()` would claim those containers and wipe them, so the template is
+   * rendered into a throwaway host and its root moved out. Safe only because
+   * none of these are ever re-rendered.
+   */
+  protected renderElement(template: TemplateResult): HTMLElement {
+    const host = document.createElement('div');
+    render(template, host);
+
+    return host.firstElementChild as HTMLElement;
+  }
+
   updateModalBottomPadding(): void {
     const footerHeight = this.$footer.outerHeight();
     const bottomPadding = parseInt($(this.$container).css('padding-bottom'));
@@ -220,30 +262,39 @@ export class BaseElementSelectorModal extends Modal {
   buildSidebarToggleView(): void {
     if (this.$sidebarToggleBtn || !this.sidebarShouldBeHidden()) return;
 
-    this.$sidebarHeader = $('<div class="sidebar-header"/>').prependTo(
-      this.$sidebar
-    );
-
-    this.$sidebarCloseBtn = Craft.ui
-      .createButton({class: 'nav-close close-btn'})
-      .attr('aria-label', Craft.t('app', 'Close'))
-      .removeClass('btn')
-      .appendTo(this.$sidebarHeader);
-
-    this.$mainHeader = $('<div class="main-header"/>').prependTo(this.$main);
-    this.$mainHeading = $(
-      `<h2 class="main-heading">${this.getActiveSourceName()}</h2>`
-    ).appendTo(this.$mainHeader);
-
-    this.$sidebarToggleBtn = Craft.ui
-      .createButton({
-        toggle: true,
-        controls: 'modal-sidebar',
-        class: 'nav-toggle',
-      })
-      .removeClass('btn')
-      .attr('aria-label', Craft.t('app', 'Show sidebar'))
-      .appendTo(this.$mainHeader);
+    // `btn-empty` and the missing `btn` reproduce what `Craft.ui.createButton()`
+    // plus the `.removeClass('btn')` these two always did emit: an icon-only
+    // button that takes its appearance from `nav-close` / `nav-toggle`.
+    const sidebarHeader = this.renderElement(html`
+      <div class="sidebar-header">
+        <button
+          type="button"
+          class="nav-close close-btn btn-empty"
+          aria-label=${Craft.t('app', 'Close')}
+          ${ref((el) => (this.$sidebarCloseBtn = $(el)))}
+        ></button>
+      </div>
+    `);
+    this.$sidebar[0].prepend(sidebarHeader);
+    this.$sidebarHeader = $(sidebarHeader);
+
+    const mainHeader = this.renderElement(html`
+      <div class="main-header">
+        <h2 class="main-heading" ${ref((el) => (this.$mainHeading = $(el)))}>
+          ${this.getActiveSourceName()}
+        </h2>
+        <button
+          type="button"
+          class="nav-toggle btn-empty"
+          aria-expanded="false"
+          aria-controls="modal-sidebar"
+          aria-label=${Craft.t('app', 'Show sidebar')}
+          ${ref((el) => (this.$sidebarToggleBtn = $(el)))}
+        ></button>
+      </div>
+    `);
+    this.$main[0].prepend(mainHeader);
+    this.$mainHeader = $(mainHeader);
 
     this.$sidebar.attr('id', 'modal-sidebar');
     this.closeSidebar();

From 4805b7e20665b90116e85f3682ac90d7599558a0 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 14:15:57 -0500
Subject: [PATCH 07/24] Serve index props from the element selector modal body
 action
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step toward the modal rendering the same index the CP screens do.

`element-selector-modals/body` now returns the index payload alongside the
HTML it already returned. Nothing consumes the props yet — the modal still
boots the legacy index off `html` — so this is additive and changes no
behavior.

The payload comes from a new `ModalIndexViewModel`, which is
`ContentIndexViewModel` with two differences the modal needs: sources resolve
in the `modal` context rather than `index`, and they are narrowed to the
source keys the opener allows, since a relation field may offer only some of
an element type's sources. Both ride on the resolution `ElementIndexState`
already shares with the server-rendered shell.

`indexState()` becomes protected so the subclass can reach it.
---
 .../ElementSelectorModalController.php        |  14 +-
 src/Http/ViewModels/ContentIndexViewModel.php |   2 +-
 src/Http/ViewModels/ModalIndexViewModel.php   |  52 ++++
 .../ElementSelectorModalControllerTest.php    | 235 +++---------------
 4 files changed, 105 insertions(+), 198 deletions(-)
 create mode 100644 src/Http/ViewModels/ModalIndexViewModel.php

diff --git a/src/Http/Controllers/Elements/ElementSelectorModalController.php b/src/Http/Controllers/Elements/ElementSelectorModalController.php
index 2884e624584..5a00e720e76 100644
--- a/src/Http/Controllers/Elements/ElementSelectorModalController.php
+++ b/src/Http/Controllers/Elements/ElementSelectorModalController.php
@@ -8,6 +8,7 @@
 use CraftCms\Cms\Element\Conditions\StatusConditionRule;
 use CraftCms\Cms\Element\CurrentElementIndex;
 use CraftCms\Cms\Http\Requests\ElementIndexRequest;
+use CraftCms\Cms\Http\ViewModels\ModalIndexViewModel;
 use Illuminate\Http\JsonResponse;
 
 use function CraftCms\Cms\t;
@@ -52,6 +53,8 @@ public function __invoke(ElementIndexRequest $request, ElementIndexHtml $element
             }
         }
 
+        $sources = $request->input('sources');
+
         return new JsonResponse([
             'html' => $elementIndexHtml->html($elementType, [
                 'class' => 'content',
@@ -60,9 +63,18 @@ public function __invoke(ElementIndexRequest $request, ElementIndexHtml $element
                 'showSiteMenu' => $request->input('showSiteMenu', 'auto'),
                 'siteIds' => $request->input('siteIds'),
                 'showStatusMenu' => $hasStatuses,
-                'sources' => $request->input('sources'),
+                'sources' => $sources,
                 'statuses' => $statuses ?? null,
             ]),
+            // The same payload the index screens render from. Served alongside
+            // the HTML rather than instead of it: the modal still boots the
+            // legacy index off `html`, and will keep doing so until it mounts
+            // the Vue index.
+            'props' => new ModalIndexViewModel(
+                $elementType,
+                $request,
+                restrictToSources: is_array($sources) ? array_values($sources) : null,
+            )->toArray(),
         ]);
     }
 }
diff --git a/src/Http/ViewModels/ContentIndexViewModel.php b/src/Http/ViewModels/ContentIndexViewModel.php
index a4f9b4da27f..e9df21007dc 100644
--- a/src/Http/ViewModels/ContentIndexViewModel.php
+++ b/src/Http/ViewModels/ContentIndexViewModel.php
@@ -496,7 +496,7 @@ protected function sourceState(): array
      * The shared server-side index state — source, column, sort-option and
      * menu resolution, shared with the server-rendered index shell.
      */
-    private function indexState(): ElementIndexState
+    protected function indexState(): ElementIndexState
     {
         return app(ElementIndexState::class);
     }
diff --git a/src/Http/ViewModels/ModalIndexViewModel.php b/src/Http/ViewModels/ModalIndexViewModel.php
new file mode 100644
index 00000000000..388b36727b6
--- /dev/null
+++ b/src/Http/ViewModels/ModalIndexViewModel.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Http\ViewModels;
+
+use CraftCms\Cms\Element\Contracts\ElementInterface;
+use CraftCms\Cms\Element\ElementSources;
+use CraftCms\Cms\Http\Requests\ElementIndexRequest;
+
+/**
+ * The index payload for the element selector modal.
+ *
+ * The same shape the index screens render from, resolved in the `modal` context
+ * and narrowed to the source keys the opener allows — a relation field may only
+ * offer some of an element type's sources.
+ */
+class ModalIndexViewModel extends ContentIndexViewModel
+{
+    protected const string RENDER_CONTEXT = ElementSources::CONTEXT_MODAL;
+
+    /**
+     * @param  class-string<ElementInterface>  $elementType
+     * @param  list<string>|null  $restrictToSources  Source keys the opener allows, or null for all of them.
+     */
+    public function __construct(
+        string $elementType,
+        ElementIndexRequest $request,
+        private readonly ?array $restrictToSources = null,
+        ?string $page = null,
+    ) {
+        parent::__construct($elementType, $request, $page);
+    }
+
+    /**
+     * Unlike the index screens', these resolve in the `modal` context and honor
+     * the opener's source restriction.
+     *
+     * @return list<array<string, mixed>>
+     */
+    #[\Override]
+    public function sources(): array
+    {
+        return $this->indexState()->sources(
+            $this->elementType,
+            static::RENDER_CONTEXT,
+            withDisabled: true,
+            page: $this->page,
+            restrictTo: $this->restrictToSources,
+        )->all();
+    }
+}
diff --git a/tests/Feature/Http/Controllers/Elements/ElementSelectorModalControllerTest.php b/tests/Feature/Http/Controllers/Elements/ElementSelectorModalControllerTest.php
index af48f2af707..882382bb3d3 100644
--- a/tests/Feature/Http/Controllers/Elements/ElementSelectorModalControllerTest.php
+++ b/tests/Feature/Http/Controllers/Elements/ElementSelectorModalControllerTest.php
@@ -2,18 +2,10 @@
 
 declare(strict_types=1);
 
-use CraftCms\Cms\Address\Elements\Address;
-use CraftCms\Cms\Asset\Elements\Asset;
-use CraftCms\Cms\Asset\Models\Volume;
-use CraftCms\Cms\Asset\Models\VolumeFolder as VolumeFolderModel;
-use CraftCms\Cms\Cp\Html\ElementIndexHtml;
-use CraftCms\Cms\Element\Conditions\ElementCondition;
-use CraftCms\Cms\Element\Conditions\StatusConditionRule;
 use CraftCms\Cms\Element\ElementSources;
 use CraftCms\Cms\Entry\Elements\Entry;
 use CraftCms\Cms\Http\Controllers\Elements\ElementSelectorModalController;
 use CraftCms\Cms\User\Elements\User;
-use Illuminate\Support\Facades\Auth;
 
 use function Pest\Laravel\actingAs;
 use function Pest\Laravel\postJson;
@@ -21,202 +13,53 @@
 beforeEach(function () {
     actingAs(User::findOne());
 
-    $this->elementIndexHtmlState = new stdClass;
-
-    app()->instance(ElementIndexHtml::class, new readonly class($this->elementIndexHtmlState) extends ElementIndexHtml
-    {
-        public function __construct(
-            private stdClass $state,
-        ) {}
-
-        public function html(string $elementType, array $config = []): string
-        {
-            $this->state->elementType = $elementType;
-            $this->state->config = $config;
-            $this->state->sortOptions = $elementType::sortOptions();
-
-            return '<div class="element-index">Modal body</div>';
-        }
-    });
-});
-
-it('requires authentication', function () {
-    Auth::logout();
-
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-    ])->assertUnauthorized();
-});
-
-it('validates missing required payload', function () {
-    postJson(action(ElementSelectorModalController::class), [])
-        ->assertUnprocessable()
-        ->assertJsonValidationErrors(['elementType']);
-});
-
-it('validates invalid request payloads', function (array $payload, array $errors) {
-    postJson(action(ElementSelectorModalController::class), $payload)
-        ->assertUnprocessable()
-        ->assertJsonValidationErrors($errors);
-})->with([
-    'invalid element type' => [[
-        'elementType' => ElementSelectorModalController::class,
-    ], ['elementType']],
-    'invalid show site menu' => [[
-        'elementType' => Entry::class,
-        'showSiteMenu' => 'auto',
-    ], ['showSiteMenu']],
-    'invalid sources type' => [[
-        'elementType' => Entry::class,
-        'sources' => 123,
-    ], ['sources']],
-    'invalid source item type' => [[
-        'elementType' => Entry::class,
-        'sources' => [123],
-    ], ['sources.0']],
-    'invalid condition type' => [[
-        'elementType' => Entry::class,
-        'condition' => 123,
-    ], ['condition']],
-    'missing condition class' => [[
-        'elementType' => Entry::class,
-        'condition' => [],
-    ], ['condition']],
-    'invalid reference element ids' => [[
-        'elementType' => Entry::class,
-        'referenceElementId' => 'invalid',
-        'referenceElementOwnerId' => 'invalid',
-        'referenceElementSiteId' => 'invalid',
-    ], ['referenceElementId', 'referenceElementOwnerId', 'referenceElementSiteId']],
-]);
-
-it('renders modal HTML with the expected config', function () {
-    $response = postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-        'context' => ElementSources::CONTEXT_MODAL,
-        'showSiteMenu' => '1',
-        'sources' => ['*', 'singles'],
-    ])
-        ->assertOk()
-        ->assertExactJson([
-            'html' => '<div class="element-index">Modal body</div>',
-        ]);
-
-    expect($response->json('html'))->toBe('<div class="element-index">Modal body</div>')
-        ->and($this->elementIndexHtmlState->elementType)->toBe(Entry::class)
-        ->and($this->elementIndexHtmlState->config)->toMatchArray([
-            'class' => 'content',
+    $this->postBody = fn (array $payload = []) => postJson(
+        action(ElementSelectorModalController::class),
+        array_merge([
             'context' => ElementSources::CONTEXT_MODAL,
-            'registerJs' => false,
-            'showSiteMenu' => '1',
-            'showStatusMenu' => true,
-            'sources' => ['*', 'singles'],
-        ])
-        ->and(array_keys($this->elementIndexHtmlState->config['statuses']))->toBe(array_keys(Entry::statuses()));
-});
-
-it('accepts string sources', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-        'sources' => '[]',
-    ])->assertOk();
-
-    expect($this->elementIndexHtmlState->config['sources'])->toBe('[]');
-});
-
-it('passes the provided context through to the element index html', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-        'context' => ElementSources::CONTEXT_INDEX,
-    ])->assertOk();
-
-    expect($this->elementIndexHtmlState->config['context'])->toBe(ElementSources::CONTEXT_INDEX);
-});
-
-it('uses auto for show site menu when it is omitted', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-    ])->assertOk();
-
-    expect($this->elementIndexHtmlState->config['showSiteMenu'])->toBe('auto');
-});
-
-it('passes null statuses and disables the status menu for element types without statuses', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Address::class,
-    ])->assertOk();
-
-    expect($this->elementIndexHtmlState->elementType)->toBe(Address::class)
-        ->and($this->elementIndexHtmlState->config['showStatusMenu'])->toBeFalse()
-        ->and($this->elementIndexHtmlState->config['statuses'])->toBeNull();
-});
-
-it('filters statuses using an in status condition rule', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-        'condition' => [
-            'class' => ElementCondition::class,
             'elementType' => Entry::class,
-            'conditionRules' => [[
-                'class' => StatusConditionRule::class,
-                'operator' => 'in',
-                'values' => ['live'],
-            ]],
-        ],
-    ])->assertOk();
-
-    expect($this->elementIndexHtmlState->config['statuses']->keys()->all())->toBe(['live']);
+        ], $payload),
+        ['Accept' => 'application/json'],
+    );
 });
 
-it('filters statuses using an excluding status condition rule', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-        'condition' => [
-            'class' => ElementCondition::class,
-            'elementType' => Entry::class,
-            'conditionRules' => [[
-                'class' => StatusConditionRule::class,
-                'operator' => 'not in',
-                'values' => ['pending'],
-            ]],
-        ],
-    ])->assertOk();
-
-    expect($this->elementIndexHtmlState->config['statuses']->keys()->all())
-        ->toBe(array_values(array_diff(array_keys(Entry::statuses()), ['pending'])));
-});
+it('serves index props alongside the html the legacy index still boots from', function () {
+    $response = ($this->postBody)();
 
-it('leaves statuses unchanged when the condition has no status rule', function () {
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Entry::class,
-        'condition' => [
-            'class' => ElementCondition::class,
-            'elementType' => Entry::class,
-        ],
-    ])->assertOk();
+    $response->assertOk();
+    // The HTML is still there — the modal hasn't stopped using it yet.
+    expect($response->json('html'))->toBeString()->not->toBeEmpty();
 
-    expect(array_keys($this->elementIndexHtmlState->config['statuses']))->toBe(array_keys(Entry::statuses()));
+    $props = $response->json('props');
+    expect($props)->toBeArray();
+    expect($props['elementType'])->toBe(Entry::class);
+    expect($props['sources'])->toBeArray()->not->toBeEmpty();
 });
 
-it('activates element index context for folder-only asset selector requests', function () {
-    config()->set('filesystems.disks.test-disk', [
-        'driver' => 'local',
-        'root' => storage_path('framework/testing/element-selector-modal-controller-test/test-disk'),
-    ]);
+it('resolves sources in the modal context, not the index context', function () {
+    $props = ($this->postBody)()->json('props');
 
-    $volume = Volume::factory()->create(['fs' => 'disk:test-disk']);
-    VolumeFolderModel::factory()->create([
-        'volumeId' => $volume->id,
-        'name' => 'Docs',
-        'path' => 'docs/',
-    ]);
-
-    postJson(action(ElementSelectorModalController::class), [
-        'elementType' => Asset::class,
-        'foldersOnly' => true,
-    ])->assertOk();
+    expect($props['context'])->toBe(ElementSources::CONTEXT_MODAL);
+});
 
-    expect($this->elementIndexHtmlState->sortOptions)->toBe([
-        'title' => 'Folder',
-    ]);
+it('narrows the sources to the ones the opener allows', function () {
+    $sourceKeys = fn (array $payload) => collect(
+        ($this->postBody)($payload)->json('props.sources')
+    )
+        ->where('type', '!=', ElementSources::TYPE_HEADING)
+        ->pluck('key')
+        ->filter()
+        ->values()
+        ->all();
+
+    // Users rather than entries: they're the fixture type with more than one
+    // source, so narrowing can actually be observed.
+    $all = $sourceKeys(['elementType' => User::class]);
+    expect($all)->toContain('admins', 'inactive');
+    expect(count($all))->toBeGreaterThan(2);
+
+    expect($sourceKeys([
+        'elementType' => User::class,
+        'sources' => ['admins', 'inactive'],
+    ]))->toBe(['admins', 'inactive']);
 });

From 64c7850f6fdf7b3de6122d3de1b18b4cb37d35a2 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 15:02:05 -0500
Subject: [PATCH 08/24] Let an element index read its payload from somewhere
 other than Inertia
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`useContentIndexData()` read the index payload straight off `usePage()`, so
every composable built on it — view state, filters, columns, sort,
pagination — could only run inside an Inertia page.

It now takes an optional source to read from instead. `usePage()` is only
called when none is given, so an index outside an Inertia app doesn't reach
for one. The keys and their reactivity are identical either way, which is what
lets the rest of the `useElementIndex*` stack stay unaware of where its
payload came from.

Groundwork for the element selector modal, which will drive the same payload
over XHR from `element-selector-modals/body` rather than a page visit. No
behavior change for the index screens.
---
 .../composables/useContentIndexData.test.ts   | 49 +++++++++++++
 .../composables/useContentIndexData.ts        | 69 ++++++++++---------
 2 files changed, 87 insertions(+), 31 deletions(-)
 create mode 100644 resources/js/modules/elements/composables/useContentIndexData.test.ts

diff --git a/resources/js/modules/elements/composables/useContentIndexData.test.ts b/resources/js/modules/elements/composables/useContentIndexData.test.ts
new file mode 100644
index 00000000000..b693d0aea02
--- /dev/null
+++ b/resources/js/modules/elements/composables/useContentIndexData.test.ts
@@ -0,0 +1,49 @@
+import {expect, it, vi} from 'vite-plus/test';
+import {ref} from 'vue';
+import {
+  useContentIndexData,
+  type ContentIndexData,
+} from './useContentIndexData';
+
+vi.mock('@inertiajs/vue3', () => ({
+  usePage: () => {
+    throw new Error('usePage() should not be reached when a source is given');
+  },
+}));
+
+function payload(overrides: Partial<ContentIndexData> = {}): ContentIndexData {
+  return {
+    elementType: 'CraftCms\\Cms\\Entry\\Elements\\Entry',
+    context: 'modal',
+    search: null,
+    sources: [],
+    source: null,
+    data: [],
+    ...overrides,
+  } as unknown as ContentIndexData;
+}
+
+it('reads the payload from an explicit source instead of the Inertia page', () => {
+  const source = ref(payload({search: 'first'}));
+  const index = useContentIndexData(undefined, source);
+
+  expect(index.context).toBe('modal');
+  expect(index.search).toBe('first');
+});
+
+it('tracks the source, so an XHR-driven index updates like a page visit', () => {
+  const source = ref(payload({search: 'first', data: []}));
+  const index = useContentIndexData(undefined, source);
+
+  source.value = payload({search: 'second', data: [{id: 1}]});
+
+  expect(index.search).toBe('second');
+  expect(index.data).toHaveLength(1);
+});
+
+it('still lets extra keys win over the payload', () => {
+  const source = ref(payload({search: 'from-payload'}));
+  const index = useContentIndexData({search: 'from-extra'}, source);
+
+  expect(index.search).toBe('from-extra');
+});
diff --git a/resources/js/modules/elements/composables/useContentIndexData.ts b/resources/js/modules/elements/composables/useContentIndexData.ts
index 934540058d2..ef77ce4f124 100644
--- a/resources/js/modules/elements/composables/useContentIndexData.ts
+++ b/resources/js/modules/elements/composables/useContentIndexData.ts
@@ -1,5 +1,5 @@
 import {usePage} from '@inertiajs/vue3';
-import {computed, reactive} from 'vue';
+import {computed, reactive, toValue, type MaybeRefOrGetter} from 'vue';
 import type {PaginationData, SortItem} from '@/common/types';
 import type {ConditionConfig} from '@/modules/elements/composables/useConditionBuilder';
 import type {BulkActionItem} from '@/modules/elements/types/actions';
@@ -57,52 +57,59 @@ export type ContentIndexData = Omit<
  * object — e.g. route-param props or local state an embedded index owns.
  * Extra keys win over payload keys, so a caller can also deliberately
  * override a payload value.
+ *
+ * `source` replaces the Inertia page as where the payload is read from, for
+ * indexes that aren't a page at all. The keys and their reactivity are the
+ * same either way, so the `useElementIndex*` composables can't tell which.
  */
 export function useContentIndexData<
   Extra extends object = Record<never, never>,
->(extra?: Extra) {
-  const inertiaPage = usePage<ContentIndexData>();
+>(extra?: Extra, source?: MaybeRefOrGetter<ContentIndexData>) {
+  // Indexes that aren't an Inertia page — the element selector modal, which
+  // fetches the same payload over XHR — pass their own source. `usePage()` is
+  // only called when none is given, since it needs an Inertia app to read.
+  const inertiaPage = source === undefined ? usePage<ContentIndexData>() : null;
+  const props = (): ContentIndexData =>
+    source === undefined ? inertiaPage!.props : toValue(source);
 
   return reactive({
     // Element type
-    elementType: computed(() => inertiaPage.props.elementType),
-    elementDisplayName: computed(() => inertiaPage.props.elementDisplayName),
-    elementPluralDisplayName: computed(
-      () => inertiaPage.props.elementPluralDisplayName
-    ),
-    canHaveDrafts: computed(() => inertiaPage.props.canHaveDrafts),
+    elementType: computed(() => props().elementType),
+    elementDisplayName: computed(() => props().elementDisplayName),
+    elementPluralDisplayName: computed(() => props().elementPluralDisplayName),
+    canHaveDrafts: computed(() => props().canHaveDrafts),
 
     // Page chrome
-    context: computed(() => inertiaPage.props.context),
-    title: computed(() => inertiaPage.props.title),
-    page: computed(() => inertiaPage.props.page),
-    selectedSubnavItem: computed(() => inertiaPage.props.selectedSubnavItem),
-    showSiteMenu: computed(() => inertiaPage.props.showSiteMenu),
-    showStatusMenu: computed(() => inertiaPage.props.showStatusMenu),
+    context: computed(() => props().context),
+    title: computed(() => props().title),
+    page: computed(() => props().page),
+    selectedSubnavItem: computed(() => props().selectedSubnavItem),
+    showSiteMenu: computed(() => props().showSiteMenu),
+    showStatusMenu: computed(() => props().showStatusMenu),
 
     // Sources
-    sources: computed(() => inertiaPage.props.sources),
-    source: computed(() => inertiaPage.props.source),
-    structure: computed(() => inertiaPage.props.structure),
+    sources: computed(() => props().sources),
+    source: computed(() => props().source),
+    structure: computed(() => props().structure),
 
     // Filtering
-    status: computed(() => inertiaPage.props.status),
-    statusOptions: computed(() => inertiaPage.props.statusOptions),
-    search: computed(() => inertiaPage.props.search),
-    currentCondition: computed(() => inertiaPage.props.currentCondition),
+    status: computed(() => props().status),
+    statusOptions: computed(() => props().statusOptions),
+    search: computed(() => props().search),
+    currentCondition: computed(() => props().currentCondition),
 
     // View state
-    viewState: computed(() => inertiaPage.props.viewState),
-    viewModes: computed(() => inertiaPage.props.viewModes),
-    tableColumns: computed(() => inertiaPage.props.tableColumns),
-    defaultTableColumns: computed(() => inertiaPage.props.defaultTableColumns),
-    sort: computed(() => inertiaPage.props.sort),
-    sortOptions: computed(() => inertiaPage.props.sortOptions),
+    viewState: computed(() => props().viewState),
+    viewModes: computed(() => props().viewModes),
+    tableColumns: computed(() => props().tableColumns),
+    defaultTableColumns: computed(() => props().defaultTableColumns),
+    sort: computed(() => props().sort),
+    sortOptions: computed(() => props().sortOptions),
 
     // Results
-    data: computed(() => inertiaPage.props.data),
-    actions: computed(() => inertiaPage.props.actions),
-    pagination: computed(() => inertiaPage.props.pagination),
+    data: computed(() => props().data),
+    actions: computed(() => props().actions),
+    pagination: computed(() => props().pagination),
 
     ...(extra ?? ({} as Extra)),
   });

From 0faabf33a4824187b81eef1b60f259bcaa6a29d0 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 15:49:10 -0500
Subject: [PATCH 09/24] Let an element index navigate without Inertia

The view-mode, sort and pagination composables each built their own
`createIndexVisitor(route)`, which keeps index state in the page URL and
re-requests through an Inertia visit. Neither works for an index inside a
modal: it has no URL of its own, and the visit would replace the page behind
it.

Each now accepts a visitor instead of always making one. Pages pass nothing
and are unchanged.

Adds the modal's implementation of that contract: the query lives in a ref
and `visit()` asks a loader for a fresh payload. Same shape, so the
`useElementIndex*` composables drive it without knowing the difference.
---
 .../resources/icons/custom-icons/c-debug.svg  |  1 -
 .../icons/custom-icons/c-outline.svg          |  1 -
 .../icons/custom-icons/craft-cms.svg          |  1 -
 .../icons/custom-icons/craft-partners.svg     |  1 -
 .../icons/custom-icons/default-plugin.svg     |  3 +-
 package-lock.json                             |  7 +-
 .../modal-index-visitor.test.ts               | 66 +++++++++++++++++
 .../modal-index-visitor.ts                    | 70 +++++++++++++++++++
 .../composables/useElementIndexPagination.ts  |  7 +-
 .../composables/useElementIndexSort.ts        |  5 +-
 .../composables/useElementIndexViewMode.ts    |  7 +-
 11 files changed, 155 insertions(+), 14 deletions(-)
 create mode 100644 resources/js/modules/element-selector-modal/modal-index-visitor.test.ts
 create mode 100644 resources/js/modules/element-selector-modal/modal-index-visitor.ts

diff --git a/cms-assets/resources/icons/custom-icons/c-debug.svg b/cms-assets/resources/icons/custom-icons/c-debug.svg
index be94520453c..13602693df0 100644
--- a/cms-assets/resources/icons/custom-icons/c-debug.svg
+++ b/cms-assets/resources/icons/custom-icons/c-debug.svg
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="utf-8"?>
 <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
 	 viewBox="0 0 30 30" style="enable-background:new 0 0 30 30;" xml:space="preserve">
 <path style="fill:#E5422B;" d="M15,19c1.1,0,2.3-0.5,3.4-1.4l1.6,1.8c-1.6,1.4-3.5,2.1-5.4,2.1c-3.8,0-6.1-2.5-5.5-6c0.5-3.5,3.8-6,7.5-6
diff --git a/cms-assets/resources/icons/custom-icons/c-outline.svg b/cms-assets/resources/icons/custom-icons/c-outline.svg
index 9f3b851b809..a014f1cc564 100644
--- a/cms-assets/resources/icons/custom-icons/c-outline.svg
+++ b/cms-assets/resources/icons/custom-icons/c-outline.svg
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <svg width="108px" height="108px" viewBox="0 0 108 108" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
     <title>Craft icon</title>
     <g id="c-outline-2" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
diff --git a/cms-assets/resources/icons/custom-icons/craft-cms.svg b/cms-assets/resources/icons/custom-icons/craft-cms.svg
index e0f6ff99300..6790bec3d6e 100644
--- a/cms-assets/resources/icons/custom-icons/craft-cms.svg
+++ b/cms-assets/resources/icons/custom-icons/craft-cms.svg
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="utf-8"?>
 <svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
 	 viewBox="0 0 100 100" style="enable-background:new 0 0 100 100;" xml:space="preserve">
 <title>Craft CMS</title>
diff --git a/cms-assets/resources/icons/custom-icons/craft-partners.svg b/cms-assets/resources/icons/custom-icons/craft-partners.svg
index 6f20ab1e4de..9b575dd9430 100644
--- a/cms-assets/resources/icons/custom-icons/craft-partners.svg
+++ b/cms-assets/resources/icons/custom-icons/craft-partners.svg
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <svg width="35px" height="35px" viewBox="0 0 35 35" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
     <g id="Symbols" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
         <g id="Badges/Craft-Verification" fill-rule="nonzero" stroke="#E5422B">
diff --git a/cms-assets/resources/icons/custom-icons/default-plugin.svg b/cms-assets/resources/icons/custom-icons/default-plugin.svg
index 0dca7fba4d4..7bd87024686 100644
--- a/cms-assets/resources/icons/custom-icons/default-plugin.svg
+++ b/cms-assets/resources/icons/custom-icons/default-plugin.svg
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <svg width="100px" height="100px" viewBox="0 0 100 100" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:sketch="http://www.bohemiancoding.com/sketch/ns">
     <title>default_plugin</title>
     <g id="Plugins" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" sketch:type="MSPage">
@@ -6,4 +5,4 @@
             <path d="M30,35 L35,35 L35,55 L30,55 L30,35 L30,35 Z M64.9992187,35 L69.9992187,35 L69.9992187,50 L64.9992187,50 L64.9992187,35 L64.9992187,35 Z M69,15 L31,15 C18.3252602,21.8225 10,34.9375 10,50 C10,65.0625 18.3252602,78.1775 31,85 L69,85 C81.6747398,78.1775 90,65.0625 90,50 C90,34.9375 81.6722398,21.8225 69,15 L69,15 Z M68,80 L32,80 C27.067069,77.045 22.9422163,72.925 20,68 C16.7249384,62.5925 15,56.365 15,50 C15,43.635 16.7224385,37.4075 20,32 C22.9397164,27.075 27.067069,22.9525 32,20 L68,20 C72.932931,22.9525 77.0577837,27.075 80,32 C83.2750616,37.4075 85,43.635 85,50 C85,56.365 83.2800614,62.5925 80,68 C77.0602836,72.925 72.932931,77.045 68,80 L68,80 Z M50,75 C55.5229851,75 60.000625,72.7625 60,70 L60,60 L40,60 L40,70 C40,72.7625 44.4776399,75 50,75 L50,75 Z" id="Shape" sketch:type="MSShapeGroup"></path>
         </g>
     </g>
-</svg>
\ No newline at end of file
+</svg>
diff --git a/package-lock.json b/package-lock.json
index 1e8633ff39a..90950245c7a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -13737,9 +13737,9 @@
       }
     },
     "node_modules/globby": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/globby/-/globby-16.2.3.tgz",
-      "integrity": "sha512-VZX7TV7jmd/pn71vdnLKtgwy1IWqc3KjI9x1/UtPkwoKk5fKrNLY30ltDe3cAM5xruIN7YuuaulFt133jRrKZg==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/globby/-/globby-16.2.4.tgz",
+      "integrity": "sha512-c8B/VNLmxRcmqqenRA9t+9IyOjf9+V6lTxPaUJLqOCONdQkWZ0ETYgX0qbtJqPsgCNusT9MZ5Jeidw8Eb9tn2g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -13747,6 +13747,7 @@
         "fast-glob": "^3.3.3",
         "ignore": "^7.0.5",
         "is-path-inside": "^4.0.0",
+        "micromatch": "^4.0.8",
         "slash": "^5.1.0",
         "unicorn-magic": "^0.4.0"
       },
diff --git a/resources/js/modules/element-selector-modal/modal-index-visitor.test.ts b/resources/js/modules/element-selector-modal/modal-index-visitor.test.ts
new file mode 100644
index 00000000000..6c2ffd3fb95
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/modal-index-visitor.test.ts
@@ -0,0 +1,66 @@
+import {expect, it, vi} from 'vite-plus/test';
+import {createModalIndexVisitor} from './modal-index-visitor';
+
+it('keeps its query locally rather than in the page URL', () => {
+  const load = vi.fn().mockResolvedValue(undefined);
+  const visitor = createModalIndexVisitor(load, {source: 'admins'});
+
+  expect(visitor.currentQuery()).toEqual({source: 'admins'});
+  // The page's URL is irrelevant to a modal, and must stay untouched.
+  expect(window.location.search).toBe('');
+});
+
+it('loads a fresh payload instead of navigating', async () => {
+  const load = vi.fn().mockResolvedValue(undefined);
+  const visitor = createModalIndexVisitor(load);
+
+  visitor.merge({search: 'cat'});
+
+  expect(load).toHaveBeenCalledWith({search: 'cat'});
+});
+
+it('merges into the existing query, replacing named keys', () => {
+  const load = vi.fn().mockResolvedValue(undefined);
+  const visitor = createModalIndexVisitor(load, {source: 'admins', page: '2'});
+
+  visitor.merge({search: 'cat'});
+
+  expect(visitor.currentQuery()).toEqual({
+    source: 'admins',
+    page: '2',
+    search: 'cat',
+  });
+});
+
+it('drops a param set to null', () => {
+  const load = vi.fn().mockResolvedValue(undefined);
+  const visitor = createModalIndexVisitor(load, {search: 'cat'});
+
+  visitor.merge({search: null});
+
+  expect(visitor.currentQuery()).toEqual({});
+});
+
+it('resets the page when asked, so a filter change starts at page 1', () => {
+  const load = vi.fn().mockResolvedValue(undefined);
+  const visitor = createModalIndexVisitor(load, {page: '3', source: 'admins'});
+
+  visitor.merge({search: 'cat'}, {resetPage: true});
+
+  expect(visitor.currentQuery()).toEqual({source: 'admins', search: 'cat'});
+});
+
+it('strips bracketed forms of a replaced key', () => {
+  const load = vi.fn().mockResolvedValue(undefined);
+  const visitor = createModalIndexVisitor(load, {
+    'sort[0][field]': 'title',
+    source: 'admins',
+  });
+
+  visitor.merge({sort: 'dateCreated'});
+
+  expect(visitor.currentQuery()).toEqual({
+    source: 'admins',
+    sort: 'dateCreated',
+  });
+});
diff --git a/resources/js/modules/element-selector-modal/modal-index-visitor.ts b/resources/js/modules/element-selector-modal/modal-index-visitor.ts
new file mode 100644
index 00000000000..49f9a43b4e4
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/modal-index-visitor.ts
@@ -0,0 +1,70 @@
+import {ref, type Ref} from 'vue';
+import type {
+  IndexVisitOptions,
+  IndexVisitor,
+} from '@/modules/elements/composables/useElementIndexVisits';
+
+/**
+ * An {@link IndexVisitor} for an index that isn't a page.
+ *
+ * The page visitor keeps index state in the URL and re-requests through Inertia.
+ * A modal can do neither: it has no URL of its own, and an Inertia visit would
+ * replace the page behind it. So the query lives in a ref here, and "visiting"
+ * means asking `load` for a fresh payload.
+ *
+ * The contract is otherwise identical, which is what lets the `useElementIndex*`
+ * composables drive a modal index without knowing they are.
+ */
+export function createModalIndexVisitor(
+  load: (query: Record<string, string>) => Promise<void>,
+  initialQuery: Record<string, string> = {}
+): IndexVisitor & {query: Ref<Record<string, string>>} {
+  const query = ref<Record<string, string>>({...initialQuery});
+
+  function currentQuery(replacing: Array<string> = []): Record<string, string> {
+    return Object.fromEntries(
+      Object.entries(query.value).filter(
+        ([key]) =>
+          !replacing.some((name) => key === name || key.startsWith(`${name}[`))
+      )
+    );
+  }
+
+  function visit(
+    next: Record<string, unknown>,
+    _options: IndexVisitOptions = {}
+  ): void {
+    query.value = Object.fromEntries(
+      Object.entries(next)
+        .filter(([, value]) => value !== null && value !== undefined)
+        .map(([key, value]) => [key, String(value)])
+    );
+
+    void load(query.value);
+  }
+
+  function merge(
+    params: Record<string, unknown>,
+    options: IndexVisitOptions = {}
+  ): void {
+    const replacing = Object.keys(params);
+
+    if (options.resetPage) {
+      // Off `window` rather than the bare global: this runs before the legacy
+      // bundle has necessarily defined `Craft`, and a bare reference throws.
+      replacing.push((window as any).Craft?.pageTrigger ?? 'page');
+    }
+
+    const next: Record<string, unknown> = currentQuery(replacing);
+
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== null && value !== undefined) {
+        next[key] = value;
+      }
+    }
+
+    visit(next, options);
+  }
+
+  return {currentQuery, visit, merge, query};
+}
diff --git a/resources/js/modules/elements/composables/useElementIndexPagination.ts b/resources/js/modules/elements/composables/useElementIndexPagination.ts
index f8cf27e88ab..3b64d1e8682 100644
--- a/resources/js/modules/elements/composables/useElementIndexPagination.ts
+++ b/resources/js/modules/elements/composables/useElementIndexPagination.ts
@@ -1,6 +1,7 @@
 import {watch} from 'vue';
 import {
   createIndexVisitor,
+  type IndexVisitor,
   type ElementIndexRoute,
 } from '@/modules/elements/composables/useElementIndexVisits';
 import {useServerPagination} from '@/modules/admin-table/composables/useServerPagination';
@@ -17,9 +18,11 @@ interface ElementIndexPaginationContext {
  */
 export function useElementIndexPagination(
   props: ElementIndexPaginationContext,
-  route: ElementIndexRoute
+  route: ElementIndexRoute,
+  /** Supplied by indexes that aren't a page — see {@link createIndexVisitor}. */
+  indexVisitor?: IndexVisitor
 ) {
-  const visitor = createIndexVisitor(route);
+  const visitor = indexVisitor ?? createIndexVisitor(route);
 
   const {paginationState, paginationConfig} = useServerPagination({
     initialState: props.pagination,
diff --git a/resources/js/modules/elements/composables/useElementIndexSort.ts b/resources/js/modules/elements/composables/useElementIndexSort.ts
index 21c5b23ab46..40defe548bc 100644
--- a/resources/js/modules/elements/composables/useElementIndexSort.ts
+++ b/resources/js/modules/elements/composables/useElementIndexSort.ts
@@ -1,6 +1,7 @@
 import {computed, type Ref, watch} from 'vue';
 import {
   createIndexVisitor,
+  type IndexVisitor,
   type ElementIndexRoute,
   type IndexRestore,
 } from '@/modules/elements/composables/useElementIndexVisits';
@@ -21,6 +22,8 @@ interface UseElementIndexSortOptions {
   route: ElementIndexRoute;
   /** Called with the server-confirmed sort, e.g. to keep a filter form in sync. */
   onSortChange?: (sort: Array<SortItem>) => void;
+  /** Supplied by indexes that aren't a page — see {@link createIndexVisitor}. */
+  visitor?: IndexVisitor;
 }
 
 /**
@@ -60,7 +63,7 @@ export function useElementIndexSort(
   viewState: Ref<ViewState>,
   options: UseElementIndexSortOptions
 ) {
-  const visitor = createIndexVisitor(options.route);
+  const visitor = options.visitor ?? createIndexVisitor(options.route);
 
   // The user's sort is persisted per source, so each source falls back to its
   // own `defaultSort` (resolved server-side) until the user sorts it.
diff --git a/resources/js/modules/elements/composables/useElementIndexViewMode.ts b/resources/js/modules/elements/composables/useElementIndexViewMode.ts
index cf31c214d2e..c14e39cf39f 100644
--- a/resources/js/modules/elements/composables/useElementIndexViewMode.ts
+++ b/resources/js/modules/elements/composables/useElementIndexViewMode.ts
@@ -1,6 +1,7 @@
 import {computed, type Ref} from 'vue';
 import {
   createIndexVisitor,
+  type IndexVisitor,
   type ElementIndexRoute,
   type IndexRestore,
 } from '@/modules/elements/composables/useElementIndexVisits';
@@ -15,9 +16,11 @@ import type {ViewMode, ViewState} from '@/modules/elements/types/view-state';
  */
 export function useElementIndexViewMode(
   route: ElementIndexRoute,
-  viewState: Ref<ViewState>
+  viewState: Ref<ViewState>,
+  /** Supplied by indexes that aren't a page — see {@link createIndexVisitor}. */
+  indexVisitor?: IndexVisitor
 ) {
-  const visitor = createIndexVisitor(route);
+  const visitor = indexVisitor ?? createIndexVisitor(route);
 
   const mode = computed<ViewMode['mode']>({
     get: () => viewState.value.mode,

From cbfc7c63d0e404d99b503010afd9d90c0f4b0937 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 15:52:14 -0500
Subject: [PATCH 10/24] Add an element index orchestrator for the selector
 modal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Composes the same stack the index screens use — view state, columns, sort,
pagination, view mode — against a payload refreshed over XHR from
`element-selector-modals/body` and the modal's visitor.

Not `useElementIndexPage`: that registers itself as the screen's active index,
which would hijack the page behind the modal, and its filter composable
submits through an Inertia form. Search and status go through the visitor
here instead.

Exposes selection in the shape the relation field consumes — the same keys
`Craft.getElementInfo()` read off chip data attributes, since `onModalSelect`
and `app/render-elements` both depend on them.
---
 .../useModalElementIndex.ts                   | 205 ++++++++++++++++++
 .../composables/useElementIndexColumns.ts     |   7 +-
 2 files changed, 210 insertions(+), 2 deletions(-)
 create mode 100644 resources/js/modules/element-selector-modal/useModalElementIndex.ts

diff --git a/resources/js/modules/element-selector-modal/useModalElementIndex.ts b/resources/js/modules/element-selector-modal/useModalElementIndex.ts
new file mode 100644
index 00000000000..68ce12b46f6
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/useModalElementIndex.ts
@@ -0,0 +1,205 @@
+import {actionClient} from '@craftcms/ui';
+import {getCoreRowModel, useVueTable} from '@tanstack/vue-table';
+import type {RowSelectionState} from '@tanstack/table-core';
+import {computed, ref, watch} from 'vue';
+import {useConditionBuilder} from '@/modules/elements/composables/useConditionBuilder';
+import {
+  useContentIndexData,
+  type ContentIndexData,
+} from '@/modules/elements/composables/useContentIndexData';
+import {useElementIndexColumns} from '@/modules/elements/composables/useElementIndexColumns';
+import {useElementIndexPagination} from '@/modules/elements/composables/useElementIndexPagination';
+import {useElementIndexSort} from '@/modules/elements/composables/useElementIndexSort';
+import {useElementIndexViewMode} from '@/modules/elements/composables/useElementIndexViewMode';
+import {useElementIndexViewState} from '@/modules/elements/composables/useElementIndexViewState';
+import {createModalIndexVisitor} from './modal-index-visitor';
+
+type Row = Record<string, any>;
+
+/** What the modal hands back for each selected row. */
+export interface SelectedElement {
+  id: number;
+  siteId: number | null;
+  label: string;
+  status: string | null;
+  url: string | null;
+  hasThumb: boolean;
+}
+
+interface Options {
+  /** The `element-selector-modals/body` endpoint. */
+  url: string;
+  /** The payload the modal opened with, so the first render needs no request. */
+  initial: ContentIndexData;
+  /** Params identifying the index — element type, sources, criteria, condition. */
+  params: Record<string, unknown>;
+  /** Element ids that can't be selected (already related, self-relation). */
+  disabledElementIds?: () => number[];
+}
+
+/**
+ * An element index driven from a modal rather than an Inertia page.
+ *
+ * Same composable stack the index screens use, with two substitutions: the
+ * payload comes from a ref this refreshes over XHR instead of `usePage()`, and
+ * navigation goes through {@link createModalIndexVisitor} instead of an Inertia
+ * visit. Everything downstream — view state, filters, columns, sort, pagination
+ * — is the page's code unchanged.
+ *
+ * Deliberately not `useElementIndexPage`: that one registers itself as the
+ * active index for the whole screen, which would hijack the page behind the
+ * modal.
+ */
+export function useModalElementIndex(options: Options) {
+  const payload = ref<ContentIndexData>(options.initial);
+  const loading = ref(false);
+
+  async function load(query: Record<string, string>): Promise<void> {
+    loading.value = true;
+
+    try {
+      const {data} = await actionClient.post(options.url, {
+        ...options.params,
+        ...query,
+      });
+
+      payload.value = data.props;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  const visitor = createModalIndexVisitor(load);
+  // The composables still want a route, but nothing navigates to it — every
+  // request goes through the visitor above.
+  const route = {url: () => options.url};
+
+  const elementIndex = useContentIndexData(undefined, payload);
+  const viewState = useElementIndexViewState(elementIndex);
+  const {conditions} = useConditionBuilder({
+    initialState: elementIndex.currentCondition ?? null,
+  });
+  // Not `useElementIndexFilters`: it submits through an Inertia form, which
+  // would navigate the page behind the modal. Same params, sent the modal's way.
+  const search = ref(elementIndex.search ?? '');
+  const status = ref(elementIndex.status ?? '');
+
+  watch([search, status, conditions], () => {
+    visitor.merge(
+      {
+        search: search.value || null,
+        status: status.value || null,
+        condition: conditions.value ?? null,
+      },
+      {resetPage: true}
+    );
+  });
+  const {columns, columnOrder, columnOptions, reorder, tableColumns} =
+    useElementIndexColumns(
+      elementIndex,
+      viewState,
+      {key: 'title', label: elementIndex.elementDisplayName},
+      route,
+      visitor
+    );
+  const {sortingState, sortingConfig, sortField, sortDirection} =
+    useElementIndexSort(elementIndex, viewState, {route, visitor});
+  const {paginationState, paginationConfig} = useElementIndexPagination(
+    elementIndex,
+    route,
+    visitor
+  );
+  const {mode} = useElementIndexViewMode(route, viewState, visitor);
+
+  const rowSelection = ref<RowSelectionState>({});
+  const visibleColumns = ref({});
+
+  const disabledIds = computed(
+    () => new Set(options.disabledElementIds?.() ?? [])
+  );
+
+  const table = useVueTable<Row>({
+    get data() {
+      return elementIndex.data ?? [];
+    },
+    get columns() {
+      return columns.value;
+    },
+    state: {
+      get columnOrder() {
+        return columnOrder.value;
+      },
+      get columnVisibility() {
+        return visibleColumns.value;
+      },
+      get sorting() {
+        return sortingState.value;
+      },
+      get pagination() {
+        return paginationState.value;
+      },
+      get rowSelection() {
+        return rowSelection.value;
+      },
+    },
+    getRowId: (row) => String(row.id),
+    // Folders navigate rather than select, and an element the field already
+    // relates to can't be picked again.
+    enableRowSelection: (row) =>
+      !row.original?.isFolder &&
+      !disabledIds.value.has(Number(row.original.id)),
+    onRowSelectionChange: (updater) => {
+      rowSelection.value =
+        typeof updater === 'function' ? updater(rowSelection.value) : updater;
+    },
+    getCoreRowModel: getCoreRowModel<Row>(),
+    ...sortingConfig,
+    ...paginationConfig,
+    enableMultiSort: false,
+  });
+
+  /**
+   * The selected rows, in the shape the relation field expects.
+   *
+   * Mirrors what `Craft.getElementInfo()` read off each chip's data attributes,
+   * because `onModalSelect` and `app/render-elements` both consume it.
+   */
+  const selectedElements = computed<SelectedElement[]>(() =>
+    table.getSelectedRowModel().rows.map(({original}) => ({
+      id: Number(original.id),
+      siteId: original.siteId != null ? Number(original.siteId) : null,
+      label: String(original.label ?? original.title ?? original.id),
+      status: (original.status as string) ?? null,
+      url: (original.url as string) ?? null,
+      hasThumb: Boolean(original.hasThumb ?? original.thumb),
+    }))
+  );
+
+  const hasSelection = computed(() => selectedElements.value.length > 0);
+
+  function clearSelection(): void {
+    rowSelection.value = {};
+  }
+
+  return {
+    elementIndex,
+    table,
+    viewState,
+    conditions,
+    search,
+    status,
+    columnOptions,
+    tableColumns,
+    reorder,
+    sortField,
+    sortDirection,
+    mode,
+    loading,
+    rowSelection,
+    selectedElements,
+    hasSelection,
+    clearSelection,
+    load,
+    query: visitor.query,
+  };
+}
diff --git a/resources/js/modules/elements/composables/useElementIndexColumns.ts b/resources/js/modules/elements/composables/useElementIndexColumns.ts
index 912fd6d631f..ac766d29fa7 100644
--- a/resources/js/modules/elements/composables/useElementIndexColumns.ts
+++ b/resources/js/modules/elements/composables/useElementIndexColumns.ts
@@ -1,6 +1,7 @@
 import {computed, type Ref} from 'vue';
 import {
   createIndexVisitor,
+  type IndexVisitor,
   type ElementIndexRoute,
   type IndexRestore,
 } from '@/modules/elements/composables/useElementIndexVisits';
@@ -49,9 +50,11 @@ export function useElementIndexColumns(
   props: ElementIndexColumnsContext,
   viewState: Ref<ViewState>,
   pinned: PinnedColumn,
-  route: ElementIndexRoute
+  route: ElementIndexRoute,
+  /** Supplied by indexes that aren't a page — see {@link createIndexVisitor}. */
+  indexVisitor?: IndexVisitor
 ) {
-  const visitor = createIndexVisitor(route);
+  const visitor = indexVisitor ?? createIndexVisitor(route);
 
   // Column state is stored per source; fall back to a shared bucket when there
   // is no resolved source (e.g. the implicit "all elements" view).

From 84edc6ed8b46acb7e0129efee96c2eae655833fd Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 15:57:40 -0500
Subject: [PATCH 11/24] Mount the Vue element index inside the selector modal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The modal rendered a server-built HTML shell and booted the legacy jQuery
index into it. It now mounts the same Vue index the CP screens use, driven by
the props the body action already returns.

Selection moves with it. The modal no longer asks an index for jQuery sets:
the index pushes plain objects up, `hasSelection()` reads their count, and
`getElementInfo()` passes them through. The relation field's
`updateDisabledElementsInModal()` assigns the whole disabled set rather than
enabling and disabling ids one at a time, which also lets `removeElements()`
stop reaching into the modal's internals.

`VolumeFolderSelectorModal` deliberately keeps the legacy index: folder
picking reads `sourcePath` — the breadcrumb of the folder you navigated into,
which is what selecting the current folder means — and the Vue index has no
equivalent yet. That's now the only thing keeping `ElementIndexHtml` and the
HTML `element-indexes/*` endpoints alive.
---
 .../base-element-select-input.ts              |  23 ++-
 .../ModalElementIndex.vue                     | 164 ++++++++++++++++++
 .../asset-selector-modal.ts                   |   9 +-
 .../base-element-selector-modal.ts            | 160 +++++++++--------
 .../volume-folder-selector-modal.ts           |  57 ++++++
 5 files changed, 318 insertions(+), 95 deletions(-)
 create mode 100644 resources/js/modules/element-selector-modal/ModalElementIndex.vue

diff --git a/resources/js/modules/element-select-input/base-element-select-input.ts b/resources/js/modules/element-select-input/base-element-select-input.ts
index 13563b2ee13..5f24b7e140b 100644
--- a/resources/js/modules/element-select-input/base-element-select-input.ts
+++ b/resources/js/modules/element-select-input/base-element-select-input.ts
@@ -801,16 +801,9 @@ export class BaseElementSelectInput extends Base {
       this.elementSelect.removeItems($elements);
     }
 
-    if (this.modal) {
-      const ids: number[] = [];
-      for (let i = 0; i < $elements.length; i++) {
-        const id = $elements.eq(i).data('id');
-        if (id) ids.push(id);
-      }
-      if (ids.length) {
-        this.modal.elementIndex.enableElementsById(ids);
-      }
-    }
+    // Removing a relation makes it selectable again, so the modal's disabled
+    // set has to shrink to match.
+    this.updateDisabledElementsInModal();
 
     $elements.children('input').prop('disabled', true);
 
@@ -1231,9 +1224,15 @@ export class BaseElementSelectInput extends Base {
     }
   }
 
+  /**
+   * Republishes which elements the modal may not select.
+   *
+   * The modal's index reads this as a whole set rather than being told to
+   * enable or disable individual ids, so both directions are one assignment.
+   */
   updateDisabledElementsInModal(): void {
-    if (this.modal?.elementIndex) {
-      this.modal.elementIndex.disableElementsById(this.getDisabledElementIds());
+    if (this.modal) {
+      this.modal.settings.disabledElementIds = this.getDisabledElementIds();
     }
   }
 
diff --git a/resources/js/modules/element-selector-modal/ModalElementIndex.vue b/resources/js/modules/element-selector-modal/ModalElementIndex.vue
new file mode 100644
index 00000000000..8f758f3c691
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/ModalElementIndex.vue
@@ -0,0 +1,164 @@
+<script setup lang="ts">
+  import {t} from '@craftcms/ui';
+  import {watch} from 'vue';
+  import ElementSources from '@/modules/elements/ElementSources.vue';
+  import BaseElementIndex from '@/modules/elements/components/BaseElementIndex.vue';
+  import DataTable from '@/modules/elements/components/DataTable.vue';
+  import ElementCards from '@/modules/elements/components/ElementCards.vue';
+  import ElementThumbs from '@/modules/elements/components/ElementThumbs.vue';
+  import ElementIndexToolbar from '@/modules/elements/components/ElementIndexToolbar.vue';
+  import {TableSpacing} from '@/common/types';
+  import type {ContentIndexData} from '@/modules/elements/composables/useContentIndexData';
+  import {
+    useModalElementIndex,
+    type SelectedElement,
+  } from './useModalElementIndex';
+
+  const props = defineProps<{
+    url: string;
+    initial: ContentIndexData;
+    params: Record<string, unknown>;
+    disabledElementIds?: number[];
+  }>();
+
+  const emit = defineEmits<{
+    (event: 'selection-change', elements: SelectedElement[]): void;
+    (event: 'choose', elements: SelectedElement[]): void;
+  }>();
+
+  const index = useModalElementIndex({
+    url: props.url,
+    initial: props.initial,
+    params: props.params,
+    disabledElementIds: () => props.disabledElementIds ?? [],
+  });
+
+  const {
+    elementIndex,
+    table,
+    viewState,
+    conditions,
+    search,
+    status,
+    columnOptions,
+    tableColumns,
+    reorder,
+    sortField,
+    sortDirection,
+    mode,
+    loading,
+    selectedElements,
+    hasSelection,
+    clearSelection,
+  } = index;
+
+  // The modal's Select button and its enabled state live outside Vue, so the
+  // selection is pushed out rather than read in.
+  watch(selectedElements, (elements) => emit('selection-change', elements), {
+    deep: true,
+  });
+
+  /**
+   * `ElementSources` renders real links, because on a page picking a source IS a
+   * navigation. In a modal it must not be — following one would replace the page
+   * behind the modal — so the click is intercepted and turned into a load.
+   */
+  function onSourceClick(event: MouseEvent): void {
+    const link = (event.target as HTMLElement | null)?.closest?.('a[href]');
+
+    if (!link) {
+      return;
+    }
+
+    event.preventDefault();
+
+    const source = new URL(
+      link.getAttribute('href')!,
+      window.location.origin
+    ).searchParams.get('source');
+
+    if (source) {
+      clearSelection();
+      index.query.value = {...index.query.value, source};
+      void index.load(index.query.value);
+    }
+  }
+
+  defineExpose({selectedElements, hasSelection, clearSelection});
+</script>
+
+<template>
+  <div class="modal-element-index flex h-full">
+    <nav
+      v-if="elementIndex.sources.length > 1"
+      class="modal-element-index__sidebar sidebar"
+      :aria-label="t('Sources')"
+      @click="onSourceClick"
+    >
+      <ElementSources
+        :sources="elementIndex.sources"
+        :route="{url: () => ''}"
+        :active-source="elementIndex.source?.key"
+        :view-mode="viewState.mode !== 'table' ? viewState.mode : null"
+      />
+    </nav>
+
+    <div class="modal-element-index__main content flex-grow">
+      <BaseElementIndex
+        :table="table"
+        :selectable="true"
+        :loading="loading"
+        :from="elementIndex.pagination.from"
+        :to="elementIndex.pagination.to"
+        :total="elementIndex.pagination.total"
+        :element-type="elementIndex.elementType"
+        :source="elementIndex.source?.key"
+        context="modal"
+      >
+        <template #header>
+          <ElementIndexToolbar
+            v-model:search="search"
+            v-model:status="status"
+            v-model:conditions="conditions"
+            v-model:mode="mode"
+            v-model:sort-field="sortField"
+            v-model:sort-direction="sortDirection"
+            v-model:table-columns="tableColumns"
+            :processing="loading"
+            :status-options="elementIndex.statusOptions"
+            :view-modes="elementIndex.viewModes"
+            :column-options="columnOptions"
+            :sort-options="elementIndex.sortOptions"
+            @reorder="reorder"
+          />
+        </template>
+        <template #body>
+          <!-- Double-click chooses, matching the legacy modal's doubletap. -->
+          <div @dblclick="emit('choose', selectedElements)">
+            <ElementCards
+              v-if="mode === 'cards'"
+              :table="table"
+              :data="elementIndex.data"
+              :selectable="true"
+              :loading="loading"
+            />
+            <ElementThumbs
+              v-else-if="mode === 'thumbs'"
+              :table="table"
+              :data="elementIndex.data"
+              :selectable="true"
+              :loading="loading"
+            />
+            <DataTable
+              v-else
+              :table="table"
+              :selectable="true"
+              :loading="loading"
+              :spacing="TableSpacing.Spacious"
+            />
+          </div>
+        </template>
+      </BaseElementIndex>
+    </div>
+  </div>
+</template>
diff --git a/resources/js/modules/element-selector-modal/asset-selector-modal.ts b/resources/js/modules/element-selector-modal/asset-selector-modal.ts
index a20315eaaa5..9774451954f 100644
--- a/resources/js/modules/element-selector-modal/asset-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/asset-selector-modal.ts
@@ -80,9 +80,8 @@ export class AssetSelectorModal extends BaseElementSelectorModal {
   }
 
   override onSelectionChange(): void {
-    const $selectedElements = this.elementIndex?.getSelectedElements();
     const allowTransforms =
-      !!$selectedElements?.length && !!this.settings.transforms?.length;
+      this.selectedElements.length > 0 && !!this.settings.transforms?.length;
 
     const menuBtn = this.$selectTransformBtn?.data('menuButton') ?? null;
 
@@ -107,12 +106,10 @@ export class AssetSelectorModal extends BaseElementSelectorModal {
       AssetSelectorModal.transformUrls[transform] = {};
     }
 
-    const $selectedElements = this.elementIndex.getSelectedElements();
     const missingIds: number[] = [];
 
-    for (let i = 0; i < $selectedElements.length; i++) {
-      const $item = $($selectedElements[i]);
-      const elementId: number = Craft.getElementInfo($item).id;
+    for (const element of this.selectedElements) {
+      const elementId = element.id;
       if (
         typeof AssetSelectorModal.transformUrls[transform][elementId] ===
         'undefined'
diff --git a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
index 12d5eb7d672..b996d290cac 100644
--- a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
@@ -6,6 +6,10 @@ import {
   type ModalSettings,
 } from '@craftcms/garnish';
 import {html, render, type TemplateResult} from 'lit';
+import {createApp, type App} from 'vue';
+import {createCpComponentRegistry} from '@/bootstrap/components';
+import ModalElementIndex from './ModalElementIndex.vue';
+import type {SelectedElement} from './useModalElementIndex';
 import {ref} from 'lit/directives/ref.js';
 import {uiLayerManager} from '@/modules/slideout/slideout';
 
@@ -14,6 +18,13 @@ declare const $: any;
 
 const noop = () => {};
 
+/** What `ModalElementIndex` exposes back to the modal shell. */
+type ModalElementIndexInstance = {
+  clearSelection(): void;
+};
+
+const components = createCpComponentRegistry();
+
 // Non-runtime-dependent defaults, separated so the static getter can augment them.
 const BASE_DEFAULTS = {
   // Modal settings preserved after we overwrite this.settings in init()
@@ -81,7 +92,11 @@ export class BaseElementSelectorModal extends Modal {
   // in init() where Craft is guaranteed available.
 
   elementType: string | null = null;
-  elementIndex: any = null;
+  /** The mounted Vue index, and the app hosting it. */
+  index: ModalElementIndexInstance | null = null;
+  indexApp: App | null = null;
+  /** Pushed up by the index whenever its selection changes. */
+  selectedElements: SelectedElement[] = [];
   supportSidebarToggleView = false;
 
   // jQuery refs to modal DOM — accessed by subclasses and external code.
@@ -356,13 +371,10 @@ export class BaseElementSelectorModal extends Modal {
   }
 
   override onFadeIn(): void {
-    if (!this.elementIndex) {
+    if (!this.index) {
       this._createElementIndex();
     } else {
       this.updateModalBottomPadding();
-      if (!isMobileBrowser()) {
-        this.elementIndex.$search.focus();
-      }
     }
     super.onFadeIn();
   }
@@ -396,7 +408,7 @@ export class BaseElementSelectorModal extends Modal {
   }
 
   hasSelection(): boolean {
-    return !!this.elementIndex?.getSelectedElements().length;
+    return this.selectedElements.length > 0;
   }
 
   enableSelectBtn(): void {
@@ -430,35 +442,39 @@ export class BaseElementSelectorModal extends Modal {
   }
 
   selectElements(): void {
-    if (this.hasSelection()) {
-      if (this.elementIndex.view?.elementSelect) {
-        this.elementIndex.view.elementSelect.clearMouseUpTimeout();
-      }
+    if (!this.hasSelection()) {
+      return;
+    }
 
-      const $selectedElements = this.elementIndex.getSelectedElements();
-      const elementInfo = this.getElementInfo($selectedElements);
+    const elementInfo = this.getElementInfo(this.selectedElements);
 
-      this.onSelect(elementInfo);
+    this.onSelect(elementInfo);
 
-      if (this.settings.disableElementsOnSelect) {
-        this.elementIndex.disableElements(
-          this.elementIndex.getSelectedElements()
-        );
-      }
+    if (this.settings.disableElementsOnSelect) {
+      // Selected elements become unselectable, so the same one can't be picked
+      // twice while the modal stays open.
+      this.settings.disabledElementIds = [
+        ...(this.settings.disabledElementIds ?? []),
+        ...this.selectedElements.map((element) => element.id),
+      ];
+      this.index?.clearSelection();
+    }
 
-      if (this.settings.hideOnSelect) {
-        this.hide();
-      }
+    if (this.settings.hideOnSelect) {
+      this.hide();
     }
   }
 
-  getElementInfo($selectedElements: any): any[] {
-    const info = [];
-    for (let i = 0; i < $selectedElements.length; i++) {
-      const $element = $($selectedElements[i]);
-      info.push(Craft.getElementInfo($element));
-    }
-    return info;
+  /**
+   * Hook for subclasses to adjust what gets handed to `onSelect` — the asset
+   * modal splices a transformed URL in here.
+   *
+   * These arrive as plain objects from the index rather than being read back
+   * off chip data attributes, but carry the same keys `Craft.getElementInfo()`
+   * produced, since the relation field consumes them either way.
+   */
+  getElementInfo(elements: SelectedElement[]): any[] {
+    return elements.map((element) => ({...element}));
   }
 
   override onShow(): void {
@@ -475,10 +491,6 @@ export class BaseElementSelectorModal extends Modal {
     this.updateModalBottomPadding();
     this.updateSidebarView();
 
-    if (this.elementIndex?.searching) {
-      this.elementIndex.clearSearch(true);
-    }
-
     super.onShow();
   }
 
@@ -487,17 +499,28 @@ export class BaseElementSelectorModal extends Modal {
     super.onHide();
   }
 
+  /**
+   * The index is a Vue app rather than markup the modal owns, so it has to be
+   * unmounted explicitly — `Modal.destroy()` only clears the container.
+   */
+  override destroy(): void {
+    this.indexApp?.unmount();
+    this.indexApp = null;
+    this.index = null;
+    this.selectedElements = [];
+
+    super.destroy();
+  }
+
   onSelect(elementInfo: any): void {
     this.settings.onSelect(elementInfo);
   }
 
   override disable(): void {
-    this.elementIndex?.disable();
     super.disable();
   }
 
   override enable(): void {
-    this.elementIndex?.enable();
     super.enable();
   }
 
@@ -527,42 +550,33 @@ export class BaseElementSelectorModal extends Modal {
     Craft.sendActionRequest('POST', this.settings.bodyAction, {
       data: this.getElementIndexParams(),
     }).then((response: any) => {
-      this.$body.html(response.data.html);
-
-      if (this.$body.has('.sidebar:not(.hidden)').length) {
-        this.$body.addClass('has-sidebar');
-        this.supportSidebarToggleView = true;
-      }
-
-      this.elementIndex = Craft.createElementIndex(
-        this.elementType,
-        this.$body.children('.element-index'),
-        this.getIndexSettings()
-      );
+      this.$body.empty();
+      this.$content = this.$body;
+
+      const host = document.createElement('div');
+      host.className = 'modal-index-host';
+      this.$body[0].append(host);
+
+      this.indexApp = createApp(ModalElementIndex, {
+        url: Craft.getActionUrl(this.settings.bodyAction),
+        initial: response.data.props,
+        params: this.getElementIndexParams(),
+        disabledElementIds: this.settings.disabledElementIds ?? [],
+        onSelectionChange: (elements: SelectedElement[]) => {
+          this.selectedElements = elements;
+          this.onSelectionChange();
+        },
+        onChoose: () => this.selectElements(),
+      });
 
-      this.$main = this.elementIndex.$main;
-      this.$sidebar = this.elementIndex.$sidebar;
-      this.$content = this.$body.find('.content');
+      components.install(this.indexApp);
+      this.indexApp.config.compilerOptions.isCustomElement = (tag: string) =>
+        tag.includes('-');
+      this.index = this.indexApp.mount(
+        host
+      ) as unknown as ModalElementIndexInstance;
 
-      this.updateSidebarView();
       this.updateModalBottomPadding();
-
-      // doubletap is a jQuery synthetic event — must use jQuery .on(), NOT
-      // addListener (which uses native addEventListener and won't receive
-      // jQuery-triggered events).
-      $(this.elementIndex.$elements).on(
-        'doubletap',
-        (ev: any, touchData: any) => {
-          if (touchData.firstTap.target === touchData.secondTap.target) {
-            this.selectElements();
-          }
-        }
-      );
-
-      this.on('updateSizeAndPosition', () => {
-        this.elementIndex.handleResize();
-      });
-
       this.updateSelectBtnState();
     });
   }
@@ -583,16 +597,8 @@ export class BaseElementSelectorModal extends Modal {
         multiSelect: this.settings.multiSelect,
         waitForDoubleClicks: true,
         buttonContainer: this.$secondaryButtons,
-        onSelectionChange: () => {
-          if (this.elementIndex) {
-            this.onSelectionChange();
-          }
-        },
-        onSourcePathChange: () => {
-          if (this.elementIndex) {
-            this.onSelectionChange();
-          }
-        },
+        onSelectionChange: () => this.onSelectionChange(),
+        onSourcePathChange: () => this.onSelectionChange(),
         onSelectSource: this.onSelectSource.bind(this),
         hideSidebar: this.settings.hideSidebar,
         defaultSiteId: this.settings.defaultSiteId,
diff --git a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
index 665ebb403a4..cecda338a8e 100644
--- a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
@@ -41,6 +41,63 @@ export class VolumeFolderSelectorModal extends BaseElementSelectorModal {
     super.init('CraftCms\\Cms\\Asset\\Elements\\Asset', merged);
   }
 
+  /** The legacy jQuery index — see `_createElementIndex()` below. */
+  elementIndex: any = null;
+
+  /**
+   * Keeps the legacy element index, unlike every other selector modal.
+   *
+   * Folder picking is driven by the index's `sourcePath` — the breadcrumb of the
+   * folder you've navigated into, which is what "select the current folder"
+   * means when nothing is highlighted. The Vue index has no equivalent yet, so
+   * porting this one would lose that. It's the last thing keeping
+   * `ElementIndexHtml` and the HTML `element-indexes/*` endpoints alive.
+   */
+  override _createElementIndex(): void {
+    Craft.sendActionRequest('POST', this.settings.bodyAction, {
+      data: this.getElementIndexParams(),
+    }).then((response: any) => {
+      this.$body.html(response.data.html);
+
+      if (this.$body.has('.sidebar:not(.hidden)').length) {
+        this.$body.addClass('has-sidebar');
+        this.supportSidebarToggleView = true;
+      }
+
+      this.elementIndex = (Craft as any).createElementIndex(
+        this.elementType,
+        this.$body.children('.element-index'),
+        this.getIndexSettings()
+      );
+
+      this.$main = this.elementIndex.$main;
+      this.$sidebar = this.elementIndex.$sidebar;
+      this.$content = this.$body.find('.content');
+
+      this.updateSidebarView();
+      this.updateModalBottomPadding();
+
+      $(this.elementIndex.$elements).on(
+        'doubletap',
+        (ev: any, touchData: any) => {
+          if (touchData.firstTap.target === touchData.secondTap.target) {
+            this.selectElements();
+          }
+        }
+      );
+
+      this.on('updateSizeAndPosition', () => {
+        this.elementIndex.handleResize();
+      });
+
+      this.updateSelectBtnState();
+    });
+  }
+
+  override hasSelection(): boolean {
+    return !!this.elementIndex?.getSelectedElements().length;
+  }
+
   override getElementIndexParams(): Record<string, any> {
     return Object.assign({}, super.getElementIndexParams(), {
       foldersOnly: true,

From dfe651e20c67eb8a9e3d7d27de03b7131ce0df27 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 16:04:48 -0500
Subject: [PATCH 12/24] Give modal index rows the metadata a relation field
 needs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Selecting an element returned a 422 from `app/render-elements`, which
requires a siteId.

Index rows are `id` plus column HTML — enough to render a table, nothing that
describes the element. The legacy modal didn't have this problem because it
read each row's chip data attributes via `Craft.getElementInfo()`; with rows
as plain data there is nowhere for that to come from.

The modal's view model now adds the keys that reader produced — siteId, label,
status, url, hasThumb — through the existing `extraRowData()` hook, so they
ride along in every view mode.

`hasThumb` asks the element for its thumbnail rather than the type for
`hasThumbs()`: an asset with no preview has none even where its type does.

Verified end to end in the CP: the modal lists assets, selecting one enables
Select, choosing adds the chip, and saving persists the relation.
---
 src/Http/ViewModels/ModalIndexViewModel.php | 24 +++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/Http/ViewModels/ModalIndexViewModel.php b/src/Http/ViewModels/ModalIndexViewModel.php
index 388b36727b6..a6a149b8cc4 100644
--- a/src/Http/ViewModels/ModalIndexViewModel.php
+++ b/src/Http/ViewModels/ModalIndexViewModel.php
@@ -32,6 +32,30 @@ public function __construct(
         parent::__construct($elementType, $request, $page);
     }
 
+    /**
+     * The element metadata a relation field needs back from a selection.
+     *
+     * Index rows are otherwise column HTML keyed by attribute — enough to render
+     * a table, but not to describe the element. These are the same keys the
+     * legacy modal read off each row's chip via `Craft.getElementInfo()`, which
+     * `onModalSelect()` and `app/render-elements` both still consume.
+     *
+     * @return array<string, mixed>
+     */
+    #[\Override]
+    protected function extraRowData(ElementInterface $element): array
+    {
+        return [
+            'siteId' => $element->siteId,
+            'label' => $element->getUiLabel(),
+            'status' => $element->getStatus(),
+            'url' => $element->getUrl(),
+            // Per element, not per type: an asset with no preview renders no thumb
+            // even though its element type has them.
+            'hasThumb' => $element->getThumbHtml(30) !== null,
+        ];
+    }
+
     /**
      * Unlike the index screens', these resolve in the `modal` context and honor
      * the opener's source restriction.

From 7ceebe4e19d8099672a92d8f37886827a5ad0979 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Wed, 19 Aug 2026 16:14:30 -0500
Subject: [PATCH 13/24] Load the selector modal's stack only when one opens

Importing the registry from the relation field pulled the modal, Lit, Vue and
the whole element index component tree into every page carrying a relation
field, whether or not a modal was ever opened.

`createModal()` imports the registry on demand and `showModal()` awaits it,
guarded so a double click can't open two modals. The index component, Vue and
the component registry are likewise imported when the body action resolves
rather than at module scope.

Verified in the CP after the change: the modal still opens on the first click,
selection still enables Select, and choosing still adds the chip.
---
 .../base-element-select-input.ts              | 42 ++++++++++++++-----
 .../base-element-selector-modal.ts            | 23 ++++++----
 2 files changed, 48 insertions(+), 17 deletions(-)

diff --git a/resources/js/modules/element-select-input/base-element-select-input.ts b/resources/js/modules/element-select-input/base-element-select-input.ts
index 5f24b7e140b..d631e52352d 100644
--- a/resources/js/modules/element-select-input/base-element-select-input.ts
+++ b/resources/js/modules/element-select-input/base-element-select-input.ts
@@ -12,7 +12,6 @@ import {
   Select,
   UP_KEY,
 } from '@craftcms/garnish';
-import {createElementSelectorModal} from '@/modules/element-selector-modal/registry';
 import {elementSelectInputData} from './support';
 
 declare const Craft: any;
@@ -91,6 +90,7 @@ export class BaseElementSelectInput extends Base {
   modal: any = null;
   elementEditor: any = null;
   modalFirstOpen = true;
+  openingModal = false;
 
   $container: any = null;
   $form: any = null;
@@ -187,8 +187,9 @@ export class BaseElementSelectInput extends Base {
 
     if (this.$addElementBtn.length) {
       // activate is a jQuery synthetic event — must use jQuery .on(), not addListener.
-      $(this.$addElementBtn).on('activate.elementSelectInput', () =>
-        this.showModal()
+      $(this.$addElementBtn).on(
+        'activate.elementSelectInput',
+        () => void this.showModal()
       );
     }
 
@@ -679,7 +680,7 @@ export class BaseElementSelectInput extends Base {
           label: Craft.t('app', 'Replace'),
           callback: () => {
             this._$replaceElement = $element;
-            this.showModal();
+            void this.showModal();
           },
         });
       }
@@ -894,20 +895,41 @@ export class BaseElementSelectInput extends Base {
     callback?.();
   }
 
-  showModal(): void {
+  async showModal(): Promise<void> {
     if (!this._$replaceElement && !this.canAddMoreElements()) {
       return;
     }
 
-    if (!this.modal) {
-      this.modal = this.createModal();
-      this.modalFirstOpen = false;
-    } else {
+    if (this.modal) {
       this.modal.show();
+
+      return;
+    }
+
+    // Guards the await below: without it a double click opens two modals.
+    if (this.openingModal) {
+      return;
+    }
+
+    this.openingModal = true;
+
+    try {
+      this.modal = await this.createModal();
+      this.modalFirstOpen = false;
+    } finally {
+      this.openingModal = false;
     }
   }
 
-  createModal(): any {
+  /**
+   * The modal stack — Lit, Vue and the element index — is imported here rather
+   * than at module scope, so a page carrying a relation field doesn't load it
+   * unless a modal is actually opened.
+   */
+  async createModal(): Promise<any> {
+    const {createElementSelectorModal} =
+      await import('@/modules/element-selector-modal/registry');
+
     return createElementSelectorModal(
       this.settings.elementType,
       this.getModalSettings()
diff --git a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
index b996d290cac..5fa27c7edd5 100644
--- a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
@@ -6,9 +6,7 @@ import {
   type ModalSettings,
 } from '@craftcms/garnish';
 import {html, render, type TemplateResult} from 'lit';
-import {createApp, type App} from 'vue';
-import {createCpComponentRegistry} from '@/bootstrap/components';
-import ModalElementIndex from './ModalElementIndex.vue';
+import type {App} from 'vue';
 import type {SelectedElement} from './useModalElementIndex';
 import {ref} from 'lit/directives/ref.js';
 import {uiLayerManager} from '@/modules/slideout/slideout';
@@ -23,8 +21,6 @@ type ModalElementIndexInstance = {
   clearSelection(): void;
 };
 
-const components = createCpComponentRegistry();
-
 // Non-runtime-dependent defaults, separated so the static getter can augment them.
 const BASE_DEFAULTS = {
   // Modal settings preserved after we overwrite this.settings in init()
@@ -549,7 +545,20 @@ export class BaseElementSelectorModal extends Modal {
   _createElementIndex(): void {
     Craft.sendActionRequest('POST', this.settings.bodyAction, {
       data: this.getElementIndexParams(),
-    }).then((response: any) => {
+    }).then(async (response: any) => {
+      // Loaded on open, not at module scope: this pulls Vue and the whole
+      // element index component tree, which every page carrying a relation
+      // field would otherwise pay for whether or not a modal is ever opened.
+      const [
+        {createApp},
+        {default: ModalElementIndex},
+        {createCpComponentRegistry},
+      ] = await Promise.all([
+        import('vue'),
+        import('./ModalElementIndex.vue'),
+        import('@/bootstrap/components'),
+      ]);
+
       this.$body.empty();
       this.$content = this.$body;
 
@@ -569,7 +578,7 @@ export class BaseElementSelectorModal extends Modal {
         onChoose: () => this.selectElements(),
       });
 
-      components.install(this.indexApp);
+      createCpComponentRegistry().install(this.indexApp);
       this.indexApp.config.compilerOptions.isCustomElement = (tag: string) =>
         tag.includes('-');
       this.index = this.indexApp.mount(

From 58c00a03f2cd4f27867617caecad1ca7577dcd0d Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 21 Aug 2026 16:43:47 -0500
Subject: [PATCH 14/24] Rebuild craft-dialog on a native <dialog> element

---
 .../src/components/dialog/dialog.stories.ts   |  91 +++-
 .../src/components/dialog/dialog.styles.ts    | 125 ++++++
 .../src/components/dialog/dialog.test.ts      | 194 ++++++--
 .../src/components/dialog/dialog.ts           | 419 ++++++++++--------
 packages/craftcms-ui/src/index.ts             |   1 +
 .../src/utilities/focus-trap.test.ts          | 146 ++++++
 .../craftcms-ui/src/utilities/focus-trap.ts   | 103 +++++
 7 files changed, 854 insertions(+), 225 deletions(-)
 create mode 100644 packages/craftcms-ui/src/components/dialog/dialog.styles.ts
 create mode 100644 packages/craftcms-ui/src/utilities/focus-trap.test.ts
 create mode 100644 packages/craftcms-ui/src/utilities/focus-trap.ts

diff --git a/packages/craftcms-ui/src/components/dialog/dialog.stories.ts b/packages/craftcms-ui/src/components/dialog/dialog.stories.ts
index 7815dce34e6..77becc39a47 100644
--- a/packages/craftcms-ui/src/components/dialog/dialog.stories.ts
+++ b/packages/craftcms-ui/src/components/dialog/dialog.stories.ts
@@ -5,36 +5,99 @@ import {html} from 'lit';
 import './dialog.js';
 import type CraftDialog from './dialog.js';
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+interface DialogArgs {
+  label: string;
+  nonModal: boolean;
+  fullscreen: boolean;
+  closeOnOutsideClick: boolean;
+  body: string;
+}
+
 const meta = {
   title: 'Components/Dialog',
   component: 'craft-dialog',
-  args: {},
+  args: {
+    label: 'Dialog',
+    nonModal: false,
+    fullscreen: false,
+    closeOnOutsideClick: false,
+    body: 'This is some text within a dialog.',
+  },
   parameters: {
     layout: 'centered',
   },
-  render: function (args) {
-    function openDialog() {
-      const dialog = document.getElementById('storybook-dialog') as CraftDialog;
-      dialog.opened = true;
+  render(args: DialogArgs) {
+    const id = 'storybook-dialog';
+
+    function open() {
+      (document.getElementById(id) as CraftDialog).opened = true;
     }
 
     return html`
-      <craft-dialog label="Dialog" id="storybook-dialog">
-        This is some text within a dialog.
+      <craft-dialog
+        id=${id}
+        label=${args.label}
+        ?non-modal=${args.nonModal}
+        ?fullscreen=${args.fullscreen}
+        ?close-on-outside-click=${args.closeOnOutsideClick}
+      >
+        ${args.body}
 
         <craft-button slot="footer" data-dialog="close">Close</craft-button>
       </craft-dialog>
 
-      <craft-button @click="${openDialog}">Open Dialog</craft-button>
+      <craft-button @click=${open}>Open Dialog</craft-button>
     `;
   },
-} satisfies Meta<any>;
+} satisfies Meta<DialogArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<DialogArgs>;
+
+export const Default: Story = {};
+
+/** No footer slotted — the footer row collapses rather than leaving a gap. */
+export const NoFooter: Story = {
+  render(args: DialogArgs) {
+    function open() {
+      (document.getElementById('storybook-dialog-bare') as CraftDialog).opened =
+        true;
+    }
+
+    return html`
+      <craft-dialog id="storybook-dialog-bare" label=${args.label}>
+        ${args.body}
+      </craft-dialog>
+
+      <craft-button @click=${open}>Open Dialog</craft-button>
+    `;
+  },
+};
+
+/**
+ * Opened with `show()` rather than `showModal()`, so the dialog stays out of the
+ * top layer and content that appends itself to `<body>` — most legacy CP menus —
+ * still paints above it. The backdrop, Escape and focus containment are the
+ * component's own here.
+ */
+export const NonModal: Story = {
+  args: {nonModal: true},
+};
+
+export const Fullscreen: Story = {
+  args: {fullscreen: true},
+};
+
+/** Long content scrolls inside the body rather than growing the surface. */
+export const Scrolling: Story = {
+  args: {
+    body: Array.from(
+      {length: 40},
+      (_, i) => `Line ${i + 1} of a dialog body that has to scroll. `
+    ).join(''),
+  },
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+export const ClosesOnOutsideClick: Story = {
+  args: {closeOnOutsideClick: true},
 };
diff --git a/packages/craftcms-ui/src/components/dialog/dialog.styles.ts b/packages/craftcms-ui/src/components/dialog/dialog.styles.ts
new file mode 100644
index 00000000000..fe11ad80d57
--- /dev/null
+++ b/packages/craftcms-ui/src/components/dialog/dialog.styles.ts
@@ -0,0 +1,125 @@
+import {css} from 'lit';
+
+export default css`
+  :host {
+    display: contents;
+
+    /*
+      Sizing hooks. Declared on \`:host\` so an outer-tree rule or an inline
+      style on the host still wins — shadow-tree \`:host\` rules always lose to
+      the outer tree — and so a subclass can go near-fullscreen without
+      reaching into this component's internals.
+    */
+    --_dialog-inline-size: var(--c-dialog-inline-size, auto);
+    --_dialog-min-inline-size: var(
+      --c-dialog-min-inline-size,
+      min(90vw, 24rem)
+    );
+    --_dialog-max-inline-size: var(
+      --c-dialog-max-inline-size,
+      min(90vw, 40rem)
+    );
+    --_dialog-max-block-size: var(--c-dialog-max-block-size, 85dvh);
+  }
+
+  :host([fullscreen]) {
+    --_dialog-inline-size: var(--c-dialog-inline-size, 100vw);
+    --_dialog-min-inline-size: var(--c-dialog-min-inline-size, 100vw);
+    --_dialog-max-inline-size: var(--c-dialog-max-inline-size, 100vw);
+    --_dialog-max-block-size: var(--c-dialog-max-block-size, 100dvh);
+  }
+
+  dialog {
+    padding: 0;
+    border: 0;
+    background: none;
+    color: inherit;
+    max-width: none;
+    max-height: none;
+    overflow: visible;
+  }
+
+  dialog::backdrop {
+    background-color: rgb(0 0 0 / 0.25);
+  }
+
+  /*
+    Non-modal dialogs get no \`::backdrop\` — that pseudo only paints for the
+    top layer — so one is rendered instead. \`show()\` also leaves the dialog in
+    normal flow, hence the fixed positioning to centre it.
+  */
+  .backdrop {
+    position: fixed;
+    inset: 0;
+    background-color: rgb(0 0 0 / 0.25);
+  }
+
+  :host([non-modal]) dialog {
+    position: fixed;
+    inset: 0;
+    margin: auto;
+    z-index: 100;
+  }
+
+  .surface {
+    display: grid;
+    /* header / body / footer — the body is the only row that flexes. */
+    grid-template-rows: auto 1fr auto;
+    inline-size: var(--_dialog-inline-size);
+    min-inline-size: var(--_dialog-min-inline-size);
+    max-inline-size: var(--_dialog-max-inline-size);
+    max-block-size: var(--_dialog-max-block-size);
+    background-color: var(--c-surface-raised);
+    border-radius: var(--c-radius-md);
+    box-shadow: var(--c-shadow-lg);
+    overflow: hidden;
+  }
+
+  :host([fullscreen]) .surface {
+    border-radius: 0;
+  }
+
+  .header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: var(--c-spacing-md);
+    padding-inline: var(--c-spacing-lg);
+    padding-block-start: var(--c-spacing-lg);
+    padding-block-end: var(--c-spacing-md);
+  }
+
+  .title {
+    font-size: 1.25em;
+    margin: 0;
+  }
+
+  .close {
+    background: none;
+    border: none;
+    cursor: pointer;
+    color: inherit;
+    padding: var(--c-spacing-xs);
+    line-height: 1;
+  }
+
+  .body {
+    /*
+      Pairs with \`1fr\` above: without an explicit \`min-block-size: 0\` a grid
+      item floors at its content height, so a long slotted index would grow the
+      surface past \`--_dialog-max-block-size\` instead of scrolling inside it.
+    */
+    min-block-size: 0;
+    overflow: auto;
+    padding-inline: var(--c-spacing-lg);
+    padding-block-end: var(--c-spacing-lg);
+  }
+
+  .footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: var(--c-spacing-sm);
+    padding-inline: var(--c-spacing-lg);
+    padding-block-end: var(--c-spacing-lg);
+  }
+`;
diff --git a/packages/craftcms-ui/src/components/dialog/dialog.test.ts b/packages/craftcms-ui/src/components/dialog/dialog.test.ts
index 2ca194dd65a..bf463ba2464 100644
--- a/packages/craftcms-ui/src/components/dialog/dialog.test.ts
+++ b/packages/craftcms-ui/src/components/dialog/dialog.test.ts
@@ -2,12 +2,15 @@ import {beforeEach, describe, expect, it} from 'vite-plus/test';
 import type CraftDialog from './dialog.js';
 import './dialog.js';
 
-// happy-dom may not implement the full native <dialog> API Lion's overlay
-// controller uses; polyfill the minimum.
+// happy-dom does not implement the full native <dialog> API; polyfill the
+// minimum the component drives.
 if (typeof HTMLDialogElement !== 'undefined') {
   HTMLDialogElement.prototype.showModal ??= function (this: HTMLDialogElement) {
     this.setAttribute('open', '');
   };
+  HTMLDialogElement.prototype.show ??= function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
   HTMLDialogElement.prototype.close ??= function (this: HTMLDialogElement) {
     this.removeAttribute('open');
   };
@@ -25,80 +28,101 @@ async function createDialog(
   document.body.append(dialog);
 
   await dialog.updateComplete;
-  await new Promise((resolve) => setTimeout(resolve));
   return dialog;
 }
 
+function shadow<E extends Element = HTMLElement>(
+  dialog: CraftDialog,
+  selector: string
+): E | null {
+  return dialog.shadowRoot!.querySelector<E>(selector);
+}
+
 beforeEach(() => {
   document.body.innerHTML = '';
 });
 
-/**
- * Waits out Lion's async OverlayController show/hide cycle so its 'show'/
- * 'hide' events have synced back before the next state change.
- */
-function settle(dialog: CraftDialog): Promise<void> {
-  return dialog.updateComplete.then(
-    () => new Promise((resolve) => setTimeout(resolve))
-  );
-}
-
 describe('craft-dialog', () => {
-  it('wraps default-slot content into a slot="content" child', async () => {
+  it('projects content without relocating it', async () => {
     const dialog = await createDialog();
-    const content = dialog.querySelector('[slot="content"]');
-    expect(content).not.toBeNull();
-    expect(content!.textContent).toContain('Dialog body text');
+
+    // The whole point of the shadow-slot rewrite: a framework that rendered
+    // these nodes still owns them, in the position it put them.
+    const paragraph = dialog.querySelector('p');
+    expect(paragraph).not.toBeNull();
+    expect(paragraph!.parentElement).toBe(dialog);
+    expect(dialog.querySelector('[slot="content"]')).toBeNull();
+
+    const slot = shadow<HTMLSlotElement>(dialog, '.body slot');
+    expect(slot).not.toBeNull();
+    expect(slot!.assignedNodes({flatten: true})).toContain(paragraph);
   });
 
   it('renders the label as a header title', async () => {
     const dialog = await createDialog();
-    const title = dialog.querySelector('.craft-dialog__title');
+    const title = shadow(dialog, '.title');
+
     expect(title).not.toBeNull();
     expect(title!.textContent).toBe('Test Dialog');
   });
 
+  it('labels the dialog with the title', async () => {
+    const dialog = await createDialog();
+
+    expect(shadow(dialog, 'dialog')!.getAttribute('aria-labelledby')).toBe(
+      shadow(dialog, '.title')!.id
+    );
+  });
+
   it('renders a close button that closes the dialog', async () => {
     const dialog = await createDialog();
     dialog.opened = true;
-    await settle(dialog);
+    await dialog.updateComplete;
     expect(dialog.opened).toBe(true);
 
-    const close = dialog.querySelector<HTMLButtonElement>(
-      '.craft-dialog__close'
-    );
-    expect(close).not.toBeNull();
-    close!.click();
-    await settle(dialog);
+    shadow<HTMLButtonElement>(dialog, '.close')!.click();
+    await dialog.updateComplete;
+
     expect(dialog.opened).toBe(false);
   });
 
   it('opens when the open attribute is set before connecting', async () => {
     const dialog = await createDialog((d) => d.setAttribute('open', ''));
+
     expect(dialog.opened).toBe(true);
+    expect(shadow<HTMLDialogElement>(dialog, 'dialog')!.open).toBe(true);
   });
 
   it('reflects the opened state back to the open attribute', async () => {
     const dialog = await createDialog();
+
     dialog.opened = true;
-    await settle(dialog);
+    await dialog.updateComplete;
     expect(dialog.hasAttribute('open')).toBe(true);
 
     dialog.opened = false;
-    await settle(dialog);
+    await dialog.updateComplete;
     expect(dialog.hasAttribute('open')).toBe(false);
   });
 
-  it('moves footer-slotted children into the footer', async () => {
+  it('shows the footer only when footer content is slotted', async () => {
+    const bare = await createDialog();
+    expect(shadow(bare, '.footer')!.hasAttribute('hidden')).toBe(true);
+
     const dialog = await createDialog((d) => {
       const button = document.createElement('button');
       button.slot = 'footer';
       button.textContent = 'Done';
       d.append(button);
     });
-    const footer = dialog.querySelector('.craft-dialog__footer');
-    expect(footer).not.toBeNull();
-    expect(footer!.querySelector('button')?.textContent).toBe('Done');
+
+    const footer = shadow(dialog, '.footer')!;
+    expect(footer.hasAttribute('hidden')).toBe(false);
+    expect(
+      footer
+        .querySelector<HTMLSlotElement>('slot[name="footer"]')!
+        .assignedNodes({flatten: true})
+    ).toContain(dialog.querySelector('button'));
   });
 
   it('closes when a data-dialog="close" descendant is clicked', async () => {
@@ -110,10 +134,11 @@ describe('craft-dialog', () => {
       d.append(button);
     });
     dialog.opened = true;
-    await settle(dialog);
+    await dialog.updateComplete;
 
     dialog.querySelector<HTMLButtonElement>('[data-dialog="close"]')!.click();
-    await settle(dialog);
+    await dialog.updateComplete;
+
     expect(dialog.opened).toBe(false);
   });
 
@@ -124,10 +149,109 @@ describe('craft-dialog', () => {
     dialog.addEventListener('craft-hide', () => events.push('craft-hide'));
 
     dialog.opened = true;
-    await settle(dialog);
+    await dialog.updateComplete;
     dialog.opened = false;
-    await settle(dialog);
+    await dialog.updateComplete;
 
     expect(events).toEqual(['craft-show', 'craft-hide']);
   });
+
+  it('does not emit lifecycle events on first render', async () => {
+    const events: string[] = [];
+    const dialog = document.createElement('craft-dialog') as CraftDialog;
+    dialog.addEventListener('craft-hide', () => events.push('craft-hide'));
+    document.body.append(dialog);
+    await dialog.updateComplete;
+
+    expect(events).toEqual([]);
+  });
+
+  it('emits the after-* pair once the update settles', async () => {
+    const dialog = await createDialog();
+    const events: string[] = [];
+    dialog.addEventListener('craft-after-show', () =>
+      events.push('craft-after-show')
+    );
+    dialog.addEventListener('craft-after-hide', () =>
+      events.push('craft-after-hide')
+    );
+
+    dialog.opened = true;
+    await dialog.updateComplete;
+    await Promise.resolve();
+    expect(events).toEqual(['craft-after-show']);
+
+    dialog.opened = false;
+    await dialog.updateComplete;
+    await Promise.resolve();
+    expect(events).toEqual(['craft-after-show', 'craft-after-hide']);
+  });
+
+  describe('non-modal', () => {
+    it('opens without entering the top layer', async () => {
+      const calls: string[] = [];
+      const dialog = await createDialog((d) => d.setAttribute('non-modal', ''));
+      const native = shadow<HTMLDialogElement>(dialog, 'dialog')!;
+
+      native.show = () => {
+        calls.push('show');
+        native.setAttribute('open', '');
+      };
+      native.showModal = () => calls.push('showModal');
+
+      dialog.opened = true;
+      await dialog.updateComplete;
+
+      expect(calls).toEqual(['show']);
+    });
+
+    it('renders its own backdrop, since ::backdrop only paints for the top layer', async () => {
+      const dialog = await createDialog((d) => d.setAttribute('non-modal', ''));
+      expect(shadow(dialog, '.backdrop')).toBeNull();
+
+      dialog.opened = true;
+      await dialog.updateComplete;
+
+      expect(shadow(dialog, '.backdrop')).not.toBeNull();
+    });
+
+    it('closes on Escape, which the platform no longer handles', async () => {
+      const dialog = await createDialog((d) => d.setAttribute('non-modal', ''));
+      dialog.opened = true;
+      await dialog.updateComplete;
+
+      dialog.dispatchEvent(
+        new KeyboardEvent('keydown', {key: 'Escape', bubbles: true})
+      );
+      await dialog.updateComplete;
+
+      expect(dialog.opened).toBe(false);
+    });
+  });
+
+  describe('closeOnOutsideClick', () => {
+    it('ignores backdrop clicks by default', async () => {
+      const dialog = await createDialog();
+      dialog.opened = true;
+      await dialog.updateComplete;
+
+      shadow<HTMLDialogElement>(dialog, 'dialog')!.click();
+      await dialog.updateComplete;
+
+      expect(dialog.opened).toBe(true);
+    });
+
+    it('closes on a backdrop click when enabled', async () => {
+      const dialog = await createDialog((d) =>
+        d.setAttribute('close-on-outside-click', '')
+      );
+      dialog.opened = true;
+      await dialog.updateComplete;
+
+      shadow<HTMLDialogElement>(dialog, 'dialog')!.click();
+      await dialog.updateComplete;
+
+      expect(dialog.opened).toBe(false);
+    });
+  });
 });
diff --git a/packages/craftcms-ui/src/components/dialog/dialog.ts b/packages/craftcms-ui/src/components/dialog/dialog.ts
index 5e0f1fd6ef7..5ace4f07f54 100644
--- a/packages/craftcms-ui/src/components/dialog/dialog.ts
+++ b/packages/craftcms-ui/src/components/dialog/dialog.ts
@@ -1,74 +1,45 @@
-import {css, type PropertyValues} from 'lit';
+import type {PropertyValues, TemplateResult} from 'lit';
+import {html, LitElement, nothing} from 'lit';
 import {property} from 'lit/decorators.js';
-import {LionDialog} from '@lion/ui/dialog.js';
-import {t} from '../../utilities/translate';
-import {wireOverlayLifecycleEvents} from '../../utilities/overlay-events.js';
+import hostStyles from '@src/styles/host.styles.js';
+import {t} from '@src/utilities/translate.js';
+import {trapFocus} from '@src/utilities/focus-trap.js';
+import styles from './dialog.styles.js';
 import '../icon/icon.js';
 
-/**
- * Styles for the dialog's generated light-DOM content. The content lives in
- * the component's light DOM (Lion slots it into a native <dialog> wrapper),
- * so shadow styles can't reach its descendants; adopt a sheet into the root
- * node instead.
- */
-const contentStyles =
-  typeof CSSStyleSheet !== 'undefined' ? new CSSStyleSheet() : null;
-contentStyles?.replaceSync(`
-  .craft-dialog {
-    background-color: var(--c-surface-raised);
-    border-radius: var(--c-radius-md);
-    box-shadow: var(--c-shadow-lg);
-    min-width: min(90vw, 24rem);
-    max-width: min(90vw, 40rem);
-  }
-
-  .craft-dialog__header {
-    display: flex;
-    align-items: flex-start;
-    justify-content: space-between;
-    gap: var(--c-spacing-md);
-    padding-inline: var(--c-spacing-lg);
-    padding-block-start: var(--c-spacing-lg);
-    padding-block-end: var(--c-spacing-md);
-  }
-
-  .craft-dialog__title {
-    font-size: 1.25em;
-    margin: 0;
-  }
-
-  .craft-dialog__close {
-    background: none;
-    border: none;
-    cursor: pointer;
-    color: inherit;
-    padding: var(--c-spacing-xs);
-    line-height: 1;
-  }
-
-  .craft-dialog__body {
-    padding-inline: var(--c-spacing-lg);
-    padding-block-end: var(--c-spacing-lg);
-  }
-
-  .craft-dialog__footer {
-    display: flex;
-    justify-content: flex-end;
-    gap: var(--c-spacing-sm);
-    padding-inline: var(--c-spacing-lg);
-    padding-block-end: var(--c-spacing-lg);
-  }
-`);
+let nextId = 0;
 
 /**
- * craft-dialog is a modal dialog. Set the `open` attribute to show it;
- * default-slot children render as the body, `slot="footer"` children render
- * in a footer, and any descendant with `data-dialog="close"` closes the
- * dialog when clicked.
+ * craft-dialog is a modal dialog over a native `<dialog>`.
+ *
+ * Set the `open` attribute (or the `opened` property) to show it; default-slot
+ * children render as the body, `slot="footer"` children render in a footer, and
+ * any descendant with `data-dialog="close"` closes the dialog when clicked.
+ *
+ * The chrome lives in the shadow root and content is projected through real
+ * `<slot>` elements, so slotted nodes are never moved. That matters for
+ * framework-rendered content: Vue crashes if it re-patches a subtree a web
+ * component has relocated, and any child arriving after `connectedCallback`
+ * would miss a one-shot relocation pass anyway.
+ *
+ * Subclasses override {@link renderHeader}, {@link renderBody} and
+ * {@link renderFooter} rather than `render()`, and resize themselves through the
+ * `--c-dialog-*` custom properties.
  *
- * Note: Lion's overlay system already defines an `open()` *method*, so there
- * is no `open` boolean property — use the `open` attribute or the `opened`
- * property.
+ * @slot - The dialog body.
+ * @slot footer - Footer content, typically buttons.
+ * @csspart dialog - The native `<dialog>` element.
+ * @csspart surface - The visible panel inside it.
+ * @csspart header - The header row.
+ * @csspart title - The heading.
+ * @csspart close - The header close button.
+ * @csspart body - The scrolling body region.
+ * @csspart footer - The footer row.
+ *
+ * @fires craft-show - The dialog has opened.
+ * @fires craft-hide - The dialog has closed.
+ * @fires craft-after-show - The dialog has opened and finished updating.
+ * @fires craft-after-hide - The dialog has closed and finished updating.
  *
  * @example
  * const dialog = document.createElement('craft-dialog');
@@ -76,152 +47,248 @@ contentStyles?.replaceSync(`
  * dialog.append(message);
  * document.body.appendChild(dialog);
  */
-export default class CraftDialog extends LionDialog {
+export default class CraftDialog extends LitElement {
+  static override styles = [hostStyles, styles];
+
   /**
-   * Backs the `open` attribute (Web Awesome-era API). Named `openAttribute`
-   * because Lion already uses `open` as a method; consumers should use the
-   * attribute form or `opened`.
+   * Whether the dialog is showing.
+   *
+   * Backed by the `open` attribute. Both spellings are public — `opened` is the
+   * property, `open` the attribute — and they stay in sync in both directions.
    */
-  @property({type: Boolean, attribute: 'open', reflect: true})
-  openAttribute = false;
+  @property({type: Boolean, attribute: 'open', reflect: true}) opened = false;
 
   /** Title shown in the dialog header. */
   @property() label = '';
 
-  #contentWrapper: HTMLElement | null = null;
+  /**
+   * Open with `show()` instead of `showModal()`, keeping the dialog out of the
+   * top layer.
+   *
+   * The top layer paints above everything, including menus that append
+   * themselves to `<body>` — which is most of the legacy jQuery CP. A dialog
+   * hosting that kind of content has to stay in the normal stacking context.
+   * The platform stops managing the backdrop, Escape and focus containment in
+   * this mode, so the component supplies all three.
+   */
+  @property({type: Boolean, attribute: 'non-modal', reflect: true})
+  nonModal = false;
 
-  #titleElement: HTMLElement | null = null;
+  /** Fill the viewport. */
+  @property({type: Boolean, reflect: true}) fullscreen = false;
 
-  constructor() {
-    super();
-    wireOverlayLifecycleEvents(this);
-    this.addEventListener('opened-changed', () => {
-      // Lion's JSDoc types `opened` as boxed Boolean; coerce to primitive.
-      const opened = Boolean(this.opened);
-      if (this.openAttribute !== opened) {
-        this.openAttribute = opened;
-      }
-    });
+  /** Close when the backdrop is clicked. Off by default. */
+  @property({type: Boolean, attribute: 'close-on-outside-click'})
+  closeOnOutsideClick = false;
+
+  protected readonly titleId = `craft-dialog-title-${++nextId}`;
+
+  /**
+   * Mirrors `opened` so lifecycle events fire on a real transition rather than
+   * on the first render, where Lit reports every property as changed.
+   */
+  #lastOpened = false;
+
+  #releaseFocusTrap: (() => void) | null = null;
+
+  /**
+   * Watches light-DOM children so an empty footer collapses.
+   *
+   * Deliberately not `slotchange`: happy-dom assigns slotted nodes but never
+   * dispatches that event, so anything keyed off it is dead under the unit
+   * tests. A childList observer behaves the same in both.
+   */
+  #childObserver: MutationObserver | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    this.addEventListener('click', this.#onHostClick);
+    this.addEventListener('keydown', this.#onHostKeydown);
+
+    this.#childObserver = new MutationObserver(() => this.requestUpdate());
+    this.#childObserver.observe(this, {childList: true});
   }
 
-  static override get styles() {
-    return [
-      css`
-        :host {
-          display: contents;
-        }
-
-        dialog::backdrop {
-          background-color: rgb(0 0 0 / 0.25);
-        }
-      `,
-    ];
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+
+    this.removeEventListener('click', this.#onHostClick);
+    this.removeEventListener('keydown', this.#onHostKeydown);
+
+    this.#childObserver?.disconnect();
+    this.#childObserver = null;
+
+    this.#releaseFocusTrap?.();
+    this.#releaseFocusTrap = null;
   }
 
-  override connectedCallback() {
-    this.#adoptContentStyles();
-    this.#ensureContentWrapper();
-    super.connectedCallback();
+  /** The native element, once rendered. */
+  protected get dialogElement(): HTMLDialogElement | null {
+    return this.shadowRoot?.querySelector('dialog') ?? null;
   }
 
-  #adoptContentStyles() {
-    const root = this.getRootNode();
-    if (
-      contentStyles &&
-      (root instanceof Document || root instanceof ShadowRoot) &&
-      !root.adoptedStyleSheets.includes(contentStyles)
-    ) {
-      root.adoptedStyleSheets = [...root.adoptedStyleSheets, contentStyles];
-    }
+  protected get hasFooter(): boolean {
+    return this.querySelector(':scope > [slot="footer"]') !== null;
   }
 
-  /**
-   * Lion expects dialog content as a light-DOM child with `slot="content"`.
-   * Build it from the consumer's default-slot and footer-slot children.
-   */
-  #ensureContentWrapper() {
-    if (this.#contentWrapper?.isConnected) {
+  override render(): TemplateResult {
+    return html`
+      ${this.nonModal && this.opened
+        ? html`<div
+            class="backdrop"
+            part="backdrop"
+            @click=${this.#onBackdropClick}
+          ></div>`
+        : nothing}
+      <dialog
+        part="dialog"
+        aria-labelledby=${this.titleId}
+        @close=${this.#onNativeClose}
+        @click=${this.#onDialogClick}
+      >
+        <div class="surface" part="surface">
+          ${this.renderHeader()} ${this.renderBody()} ${this.renderFooter()}
+        </div>
+      </dialog>
+    `;
+  }
+
+  protected renderHeader(): TemplateResult {
+    return html`
+      <header class="header" part="header">
+        <h2 class="title" part="title" id=${this.titleId}>${this.label}</h2>
+        <button
+          type="button"
+          class="close"
+          part="close"
+          aria-label=${t('Close')}
+          @click=${this.#close}
+        >
+          <craft-icon name="xmark"></craft-icon>
+        </button>
+      </header>
+    `;
+  }
+
+  protected renderBody(): TemplateResult {
+    return html`<div class="body" part="body"><slot></slot></div>`;
+  }
+
+  protected renderFooter(): TemplateResult {
+    return html`
+      <footer class="footer" part="footer" ?hidden=${!this.hasFooter}>
+        <slot name="footer"></slot>
+      </footer>
+    `;
+  }
+
+  protected override updated(changed: PropertyValues): void {
+    super.updated(changed);
+
+    if (this.opened === this.#lastOpened) {
       return;
     }
 
-    const wrapper = document.createElement('div');
-    wrapper.slot = 'content';
-    wrapper.classList.add('craft-dialog');
-
-    const body = document.createElement('div');
-    body.classList.add('craft-dialog__body');
-    body.append(
-      ...Array.from(this.childNodes).filter(
-        (node) => !(node instanceof Element) || node.slot === ''
-      )
-    );
-
-    const footerNodes = Array.from(this.children).filter(
-      (child) => child.slot === 'footer'
-    );
-
-    wrapper.append(this.#buildHeader(), body);
-
-    if (footerNodes.length > 0) {
-      const footer = document.createElement('footer');
-      footer.classList.add('craft-dialog__footer');
-      footer.append(...footerNodes);
-      wrapper.append(footer);
-    }
+    this.#lastOpened = this.opened;
+    this.opened ? this.#showDialog() : this.#hideDialog();
+    this.#emitLifecycle(this.opened);
+  }
 
-    wrapper.addEventListener('click', (event) => {
-      const target = event.target as HTMLElement;
-      if (target.closest?.('[data-dialog="close"]')) {
-        this.opened = false;
-      }
-    });
+  #showDialog(): void {
+    const dialog = this.dialogElement;
+
+    if (dialog && !dialog.open) {
+      // `showModal()` throws if the dialog is already open, hence the guard.
+      this.nonModal ? dialog.show() : dialog.showModal();
+    }
 
-    this.append(wrapper);
-    this.#contentWrapper = wrapper;
+    // `showModal()` contains focus for us; `show()` does not.
+    if (this.nonModal) {
+      this.#releaseFocusTrap?.();
+      this.#releaseFocusTrap = trapFocus(this);
+    }
   }
 
-  #buildHeader(): HTMLElement {
-    const header = document.createElement('header');
-    header.classList.add('craft-dialog__header');
+  #hideDialog(): void {
+    const dialog = this.dialogElement;
+
+    if (dialog?.open) {
+      dialog.close();
+    }
+
+    this.#releaseFocusTrap?.();
+    this.#releaseFocusTrap = null;
+  }
 
-    const title = document.createElement('h2');
-    title.classList.add('craft-dialog__title');
-    title.textContent = this.label;
-    this.#titleElement = title;
+  /**
+   * `craft-show`/`craft-hide` fire on the transition; the `after` pair fires
+   * once this update has settled. All four bubble and are composed, so
+   * listeners outside the host's shadow root receive them.
+   */
+  #emitLifecycle(opened: boolean): void {
+    this.#dispatch(opened ? 'craft-show' : 'craft-hide');
 
-    const close = document.createElement('button');
-    close.type = 'button';
-    close.classList.add('craft-dialog__close');
-    close.setAttribute('aria-label', t('Close'));
-    close.setAttribute('data-dialog', 'close');
+    void this.updateComplete.then(() => {
+      if (this.opened !== opened) {
+        return;
+      }
 
-    const icon = document.createElement('craft-icon');
-    icon.setAttribute('name', 'xmark');
-    close.append(icon);
+      this.#dispatch(opened ? 'craft-after-show' : 'craft-after-hide');
+    });
+  }
 
-    header.append(title, close);
-    return header;
+  #dispatch(name: string): void {
+    this.dispatchEvent(new CustomEvent(name, {bubbles: true, composed: true}));
   }
 
-  protected override updated(changed: PropertyValues) {
-    super.updated(changed);
+  #close = (): void => {
+    this.opened = false;
+  };
+
+  /**
+   * The platform closes a modal dialog on Escape by itself and fires `close`;
+   * syncing here covers that as well as any direct `dialogElement.close()`.
+   */
+  #onNativeClose = (): void => {
+    this.opened = false;
+  };
+
+  /** Escape is ours to handle only when the platform isn't managing the dialog. */
+  #onHostKeydown = (event: KeyboardEvent): void => {
+    if (this.nonModal && this.opened && event.key === 'Escape') {
+      event.preventDefault();
+      this.#close();
+    }
+  };
 
-    if (changed.has('openAttribute') && this.openAttribute !== this.opened) {
-      this.opened = this.openAttribute;
+  /**
+   * Honors the `data-dialog="close"` convention on slotted content. Shadow-tree
+   * clicks retarget to the host and can't be matched with `closest()`, so the
+   * header's own close button is wired directly instead.
+   */
+  #onHostClick = (event: MouseEvent): void => {
+    const target = event.target as HTMLElement | null;
+
+    if (target?.closest?.('[data-dialog="close"]')) {
+      this.#close();
     }
+  };
 
-    if (changed.has('label') && this.#titleElement) {
-      this.#titleElement.textContent = this.label;
+  /** A click on the backdrop of a modal dialog targets the dialog itself. */
+  #onDialogClick = (event: MouseEvent): void => {
+    if (this.closeOnOutsideClick && event.target === this.dialogElement) {
+      this.#close();
     }
-  }
+  };
+
+  #onBackdropClick = (): void => {
+    if (this.closeOnOutsideClick) {
+      this.#close();
+    }
+  };
 }
 
 if (!customElements.get('craft-dialog')) {
   customElements.define('craft-dialog', CraftDialog);
 }
-
-declare global {
-  interface HTMLElementTagNameMap {
-    'craft-dialog': CraftDialog;
-  }
-}
diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index ca4b776b663..fa3b9d6edd3 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -111,6 +111,7 @@ export * from './utilities/dom.js';
 export * from './utilities/attrs.js';
 export * from './utilities/thumbnail-loader.js';
 export * from './utilities/create.js';
+export * from './utilities/focus-trap.js';
 
 // Services
 export {ConfigService} from './services/Config.js';
diff --git a/packages/craftcms-ui/src/utilities/focus-trap.test.ts b/packages/craftcms-ui/src/utilities/focus-trap.test.ts
new file mode 100644
index 00000000000..47932c8b92a
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/focus-trap.test.ts
@@ -0,0 +1,146 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+import {focusableWithin, trapFocus} from './focus-trap.js';
+
+/** A host with chrome in its shadow root and a slot in the middle, like a dialog. */
+class TrapHost extends HTMLElement {
+  connectedCallback() {
+    if (this.shadowRoot) {
+      return;
+    }
+
+    const root = this.attachShadow({mode: 'open'});
+    root.innerHTML = `<button class="close">Close</button><slot></slot>`;
+  }
+}
+
+if (!customElements.get('trap-host')) {
+  customElements.define('trap-host', TrapHost);
+}
+
+function createHost(lightDom = ''): TrapHost {
+  const host = document.createElement('trap-host') as TrapHost;
+  host.innerHTML = lightDom;
+  document.body.append(host);
+  return host;
+}
+
+function tab(host: HTMLElement, from: HTMLElement, shiftKey = false): void {
+  from.focus();
+  from.dispatchEvent(
+    // `composed` matters: a non-composed event dispatched in a shadow tree
+    // never reaches the host, where the trap listens.
+    new KeyboardEvent('keydown', {
+      key: 'Tab',
+      shiftKey,
+      bubbles: true,
+      composed: true,
+    })
+  );
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('focusableWithin', () => {
+  it('collects across the shadow tree and slotted light DOM', () => {
+    const host = createHost(
+      '<button id="a">A</button><button id="b">B</button>'
+    );
+
+    expect(focusableWithin(host).map((el) => el.className || el.id)).toEqual([
+      'close',
+      'a',
+      'b',
+    ]);
+  });
+
+  it('skips disabled, inert and aria-hidden elements', () => {
+    const host = createHost(`
+      <button id="a" disabled>A</button>
+      <button id="b" inert>B</button>
+      <button id="c" aria-hidden="true">C</button>
+      <button id="d">D</button>
+    `);
+
+    expect(focusableWithin(host).map((el) => el.className || el.id)).toEqual([
+      'close',
+      'd',
+    ]);
+  });
+
+  it('skips tabindex="-1" elements', () => {
+    const host = createHost(
+      '<button id="a" tabindex="-1">A</button><button id="b">B</button>'
+    );
+
+    expect(focusableWithin(host).map((el) => el.className || el.id)).toEqual([
+      'close',
+      'b',
+    ]);
+  });
+});
+
+describe('trapFocus', () => {
+  it('wraps Tab from the last element to the first', () => {
+    const host = createHost(
+      '<button id="a">A</button><button id="b">B</button>'
+    );
+    trapFocus(host);
+
+    const last = host.querySelector<HTMLButtonElement>('#b')!;
+    tab(host, last);
+
+    expect(host.shadowRoot!.activeElement).toBe(
+      host.shadowRoot!.querySelector('.close')
+    );
+  });
+
+  it('wraps Shift-Tab from the first element to the last', () => {
+    const host = createHost(
+      '<button id="a">A</button><button id="b">B</button>'
+    );
+    trapFocus(host);
+
+    const first = host.shadowRoot!.querySelector<HTMLButtonElement>('.close')!;
+    tab(host, first, true);
+
+    expect(document.activeElement).toBe(host.querySelector('#b'));
+  });
+
+  it('leaves interior Tab presses alone', () => {
+    const host = createHost(
+      '<button id="a">A</button><button id="b">B</button>'
+    );
+    trapFocus(host);
+
+    const middle = host.querySelector<HTMLButtonElement>('#a')!;
+    tab(host, middle);
+
+    // No wrap: focus stays where the browser would take it from here.
+    expect(document.activeElement).toBe(middle);
+  });
+
+  it('stops trapping once released', () => {
+    const host = createHost(
+      '<button id="a">A</button><button id="b">B</button>'
+    );
+    const release = trapFocus(host);
+    release();
+
+    const last = host.querySelector<HTMLButtonElement>('#b')!;
+    tab(host, last);
+
+    expect(document.activeElement).toBe(last);
+  });
+
+  it('does nothing when there is nothing to focus', () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    trapFocus(host);
+
+    expect(() =>
+      host.dispatchEvent(new KeyboardEvent('keydown', {key: 'Tab'}))
+    ).not.toThrow();
+  });
+});
diff --git a/packages/craftcms-ui/src/utilities/focus-trap.ts b/packages/craftcms-ui/src/utilities/focus-trap.ts
new file mode 100644
index 00000000000..b4697a5e849
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/focus-trap.ts
@@ -0,0 +1,103 @@
+/**
+ * Focus containment for overlays that can't use the platform's own.
+ *
+ * A `<dialog>` opened with `showModal()` gets focus containment from the
+ * browser. One opened with `show()` does not — it stays in the normal stacking
+ * context, which is the point (top-layer dialogs paint above `<body>`-appended
+ * menus and make them unclickable), but the price is that Tab walks straight
+ * out of it. These helpers pay that price back.
+ */
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  'details > summary',
+  'iframe',
+  'object',
+  'embed',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]',
+  '[tabindex]',
+].join(',');
+
+function isTabbable(el: HTMLElement): boolean {
+  if (el.hasAttribute('disabled') || el.hasAttribute('inert')) {
+    return false;
+  }
+
+  if (el.getAttribute('aria-hidden') === 'true' || el.hidden) {
+    return false;
+  }
+
+  return el.tabIndex >= 0;
+}
+
+/**
+ * Tab-reachable elements inside a host, shadow tree first.
+ *
+ * A host's shadow tree and its slotted light-DOM children are separate trees,
+ * so this walks both. Concatenating them approximates document order — resolving
+ * it exactly would mean matching every `<slot>`'s assigned nodes against that
+ * slot's position in the shadow tree. The approximation holds for the shape
+ * these overlays use (chrome rendered in shadow, content slotted into the
+ * middle), and only the first and last entries are ever used.
+ *
+ * Deliberately does not filter on visibility: `isVisible()` depends on layout,
+ * which happy-dom does not compute, and a trap that finds nothing under test is
+ * worse than one that occasionally includes a hidden control.
+ */
+export function focusableWithin(host: HTMLElement): HTMLElement[] {
+  const roots: ParentNode[] = host.shadowRoot
+    ? [host.shadowRoot, host]
+    : [host];
+
+  return roots
+    .flatMap((root) =>
+      Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+    )
+    .filter(isTabbable);
+}
+
+/**
+ * Wrap Tab navigation around the focusable elements inside `host`.
+ *
+ * Returns a disposer; call it when the overlay closes. Installing a second trap
+ * on the same host without releasing the first leaves both listeners attached,
+ * so callers should hold the disposer rather than re-trapping.
+ */
+export function trapFocus(host: HTMLElement): () => void {
+  const onKeydown = (event: KeyboardEvent): void => {
+    if (event.key !== 'Tab') {
+      return;
+    }
+
+    const focusable = focusableWithin(host);
+
+    if (focusable.length === 0) {
+      return;
+    }
+
+    const first = focusable[0]!;
+    const last = focusable[focusable.length - 1]!;
+    // `composedPath()` rather than `target`, so a focused node inside a nested
+    // shadow root still matches the element we collected.
+    const active = event.composedPath()[0] as HTMLElement | undefined;
+
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+
+  host.addEventListener('keydown', onKeydown);
+
+  return () => host.removeEventListener('keydown', onKeydown);
+}

From 2340eb6fa39dad2efbdc0e56ec241704ac313f3a Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 21 Aug 2026 16:51:10 -0500
Subject: [PATCH 15/24] Add the framework-agnostic element selector core

---
 packages/craftcms-ui/package.json             |   9 +
 packages/craftcms-ui/scripts/build.js         |   2 +-
 .../asset-selector-controller.test.ts         | 219 +++++++
 .../asset-selector-controller.ts              | 153 +++++
 .../element-selector-controller.test.ts       | 599 ++++++++++++++++++
 .../element-selector-controller.ts            | 426 +++++++++++++
 .../src/core/element-selector/index.ts        |  36 ++
 .../core/element-selector/registry.test.ts    | 105 +++
 .../src/core/element-selector/registry.ts     |  80 +++
 .../src/core/element-selector/types.ts        | 174 +++++
 .../volume-folder-selector-controller.test.ts | 142 +++++
 .../volume-folder-selector-controller.ts      | 142 +++++
 packages/craftcms-ui/src/index.ts             |   1 +
 packages/craftcms-ui/vitest.config.ts         |  12 +
 14 files changed, 2099 insertions(+), 1 deletion(-)
 create mode 100644 packages/craftcms-ui/src/core/element-selector/asset-selector-controller.test.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/asset-selector-controller.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/index.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/registry.test.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/registry.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/types.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.test.ts
 create mode 100644 packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.ts

diff --git a/packages/craftcms-ui/package.json b/packages/craftcms-ui/package.json
index e20b513aa60..37d1a68a3e1 100644
--- a/packages/craftcms-ui/package.json
+++ b/packages/craftcms-ui/package.json
@@ -44,6 +44,15 @@
       "development": "./src/components/*.ts",
       "default": "./dist/components/*.ts.mjs"
     },
+    "./core": {
+      "development": "./src/core/element-selector/index.ts",
+      "types": "./dist/core/element-selector/index.ts.d.mts",
+      "import": "./dist/core/element-selector/index.ts.mjs"
+    },
+    "./core/*": {
+      "development": "./src/core/*.ts",
+      "default": "./dist/core/*.ts.mjs"
+    },
     "./services/*": {
       "development": "./src/services/*.ts",
       "default": "./dist/services/*.ts.mjs"
diff --git a/packages/craftcms-ui/scripts/build.js b/packages/craftcms-ui/scripts/build.js
index d61b6315868..99fa7ac3a81 100755
--- a/packages/craftcms-ui/scripts/build.js
+++ b/packages/craftcms-ui/scripts/build.js
@@ -45,8 +45,8 @@ async function generateBundle(config = {}) {
         )),
         ...(await resolveFrom('./src/services/**/!(*.(styles|test)).ts')),
         ...(await resolveFrom('./src/utilities/**/!(*.(styles|test)).ts')),
-        ...(await resolveFrom('./src/services/**/!(*.(styles|test)).ts')),
         ...(await resolveFrom('./src/factory/**/!(*.(styles|test)).ts')),
+        ...(await resolveFrom('./src/core/**/!(*.(styles|test)).ts')),
       },
       minify: !isDeveloping,
       external: ['lit', '@lion/ui'],
diff --git a/packages/craftcms-ui/src/core/element-selector/asset-selector-controller.test.ts b/packages/craftcms-ui/src/core/element-selector/asset-selector-controller.test.ts
new file mode 100644
index 00000000000..d15eb1a8e3c
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/asset-selector-controller.test.ts
@@ -0,0 +1,219 @@
+import {beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+import {AssetSelectorController} from './asset-selector-controller.js';
+import type {AssetSelectorOptions} from './asset-selector-controller.js';
+import type {ElementInfo} from './types.js';
+
+const ASSET = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
+
+const TRANSFORMS = [
+  {handle: 'thumb', name: 'Thumbnail'},
+  {handle: 'large', name: 'Large'},
+];
+
+function asset(id: number): ElementInfo {
+  return {
+    id,
+    siteId: 1,
+    label: `Asset ${id}`,
+    status: null,
+    url: `/uploads/asset-${id}.jpg`,
+    hasThumb: true,
+  };
+}
+
+function create(options: Partial<AssetSelectorOptions> = {}) {
+  return new AssetSelectorController({
+    elementType: ASSET,
+    transforms: TRANSFORMS,
+    hideOnSelect: false,
+    loadIndexBody: async () => ({html: '', props: {}}),
+    fetchTransformUrl: async (id, handle) => `/transformed/${handle}/${id}.jpg`,
+    ...options,
+  });
+}
+
+beforeEach(() => {
+  // Static by design (transform URLs are stable per asset and modals are built
+  // per relation field), so it has to be reset between tests.
+  AssetSelectorController.transformUrls = {};
+});
+
+describe('canApplyTransform', () => {
+  it('is false with nothing selected', () => {
+    expect(create().canApplyTransform).toBe(false);
+  });
+
+  it('is true once assets are selected', () => {
+    const controller = create();
+    controller.setSelection([asset(1)]);
+
+    expect(controller.canApplyTransform).toBe(true);
+  });
+
+  it('is false when no transforms are configured', () => {
+    const controller = create({transforms: []});
+    controller.setSelection([asset(1)]);
+
+    expect(controller.canApplyTransform).toBe(false);
+  });
+});
+
+describe('selectWithTransform', () => {
+  it('splices the transformed URL into the payload', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.setSelection([asset(1), asset(2)]);
+
+    await controller.selectWithTransform('thumb');
+
+    expect(onSelect.mock.calls[0]![0].map((e: ElementInfo) => e.url)).toEqual([
+      '/transformed/thumb/1.jpg',
+      '/transformed/thumb/2.jpg',
+    ]);
+  });
+
+  it('reports the transform in the select meta', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.setSelection([asset(1)]);
+
+    await controller.selectWithTransform('large');
+
+    expect(onSelect.mock.calls[0]![1]).toEqual({transform: 'large'});
+  });
+
+  it('leaves the transform unset for a plain submit', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.setSelection([asset(1)]);
+
+    await controller.submit();
+
+    expect(onSelect.mock.calls[0]![1]).toEqual({transform: null});
+    expect(onSelect.mock.calls[0]![0][0].url).toBe('/uploads/asset-1.jpg');
+  });
+
+  it('resets the transform after submitting', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.setSelection([asset(1)]);
+
+    await controller.selectWithTransform('thumb');
+    await controller.submit();
+
+    expect(onSelect.mock.calls[1]![1]).toEqual({transform: null});
+  });
+
+  it('holds busy across the fetches', async () => {
+    let release: (url: string) => void = () => {};
+    const controller = create({
+      fetchTransformUrl: () =>
+        new Promise<string>((resolve) => {
+          release = resolve;
+        }),
+    });
+    controller.setSelection([asset(1)]);
+
+    const pending = controller.selectWithTransform('thumb');
+    expect(controller.state.busy).toBe(true);
+
+    release('/transformed/thumb/1.jpg');
+    await pending;
+
+    expect(controller.state.busy).toBe(false);
+  });
+});
+
+describe('the URL cache', () => {
+  it('fetches each asset once, sequentially', async () => {
+    const order: number[] = [];
+    const fetchTransformUrl = vi.fn(async (id: number, handle: string) => {
+      order.push(id);
+      return `/transformed/${handle}/${id}.jpg`;
+    });
+    const controller = create({fetchTransformUrl});
+    controller.setSelection([asset(1), asset(2)]);
+
+    await controller.selectWithTransform('thumb');
+    await controller.selectWithTransform('thumb');
+
+    expect(fetchTransformUrl).toHaveBeenCalledTimes(2);
+    expect(order).toEqual([1, 2]);
+  });
+
+  it('only fetches the assets it is missing', async () => {
+    const fetchTransformUrl = vi.fn(
+      async (id: number, handle: string) => `/transformed/${handle}/${id}.jpg`
+    );
+    const controller = create({fetchTransformUrl});
+
+    controller.setSelection([asset(1)]);
+    await controller.selectWithTransform('thumb');
+    fetchTransformUrl.mockClear();
+
+    controller.setSelection([asset(1), asset(2)]);
+    await controller.selectWithTransform('thumb');
+
+    expect(fetchTransformUrl.mock.calls.map(([id]) => id)).toEqual([2]);
+  });
+
+  it('keys the cache per transform', async () => {
+    const fetchTransformUrl = vi.fn(
+      async (id: number, handle: string) => `/transformed/${handle}/${id}.jpg`
+    );
+    const controller = create({fetchTransformUrl});
+    controller.setSelection([asset(1)]);
+
+    await controller.selectWithTransform('thumb');
+    await controller.selectWithTransform('large');
+
+    expect(fetchTransformUrl).toHaveBeenCalledTimes(2);
+    expect(Object.keys(AssetSelectorController.transformUrls)).toEqual([
+      'thumb',
+      'large',
+    ]);
+  });
+
+  it('shares the cache across instances', async () => {
+    const fetchTransformUrl = vi.fn(
+      async (id: number, handle: string) => `/transformed/${handle}/${id}.jpg`
+    );
+
+    const first = create({fetchTransformUrl});
+    first.setSelection([asset(1)]);
+    await first.selectWithTransform('thumb');
+
+    const second = create({fetchTransformUrl});
+    second.setSelection([asset(1)]);
+    await second.selectWithTransform('thumb');
+
+    expect(fetchTransformUrl).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to the untransformed URL when a transform fails', async () => {
+    const onSelect = vi.fn();
+    const controller = create({
+      onSelect,
+      fetchTransformUrl: async () => {
+        throw new Error('generate-transform blew up');
+      },
+    });
+    controller.setSelection([asset(1)]);
+
+    await controller.selectWithTransform('thumb');
+
+    expect(controller.state.busy).toBe(false);
+    expect(onSelect.mock.calls[0]![0][0].url).toBe('/uploads/asset-1.jpg');
+  });
+
+  it('caches a false result so a failed transform is not retried', async () => {
+    const fetchTransformUrl = vi.fn(async () => false as const);
+    const controller = create({fetchTransformUrl});
+    controller.setSelection([asset(1)]);
+
+    await controller.selectWithTransform('thumb');
+    await controller.selectWithTransform('thumb');
+
+    expect(fetchTransformUrl).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/craftcms-ui/src/core/element-selector/asset-selector-controller.ts b/packages/craftcms-ui/src/core/element-selector/asset-selector-controller.ts
new file mode 100644
index 00000000000..778e8e7fe81
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/asset-selector-controller.ts
@@ -0,0 +1,153 @@
+import {actionClient} from '@src/utilities/api/actionClient.js';
+import {ElementSelectorController} from './element-selector-controller.js';
+import type {
+  ElementIndexAdapter,
+  ElementInfo,
+  ElementSelectorOptions,
+  SelectMeta,
+} from './types.js';
+
+export interface AssetTransform {
+  handle: string;
+  name: string;
+}
+
+/** Resolves an asset's URL under a transform, or `false` if it has none. */
+export type FetchTransformUrl = (
+  assetId: number,
+  handle: string
+) => Promise<string | false>;
+
+export interface AssetSelectorOptions extends ElementSelectorOptions {
+  /** Transforms offered before selecting. Empty means no transform menu. */
+  transforms?: AssetTransform[];
+  /** Test seam; defaults to a POST to `assets/generate-transform`. */
+  fetchTransformUrl?: FetchTransformUrl;
+}
+
+const defaultFetchTransformUrl: FetchTransformUrl = async (assetId, handle) => {
+  const {data} = await actionClient.post('assets/generate-transform', {
+    assetId,
+    handle,
+  });
+
+  return (data?.url as string | undefined) || false;
+};
+
+/**
+ * Adds image transforms to the element selector.
+ *
+ * The user may pick a transform instead of plain Select; the chosen transform's
+ * URL is resolved for every selected asset and spliced into the payload.
+ *
+ * @example
+ * const controller = new AssetSelectorController({
+ *   elementType: 'CraftCms\\Cms\\Asset\\Elements\\Asset',
+ *   transforms: [{handle: 'thumb', name: 'Thumbnail'}],
+ *   onSelect: (elements, {transform}) => …,
+ * });
+ *
+ * await controller.selectWithTransform('thumb');
+ */
+export class AssetSelectorController<
+  A extends ElementIndexAdapter = ElementIndexAdapter,
+> extends ElementSelectorController<A> {
+  /**
+   * Cross-instance cache of resolved URLs, keyed `[handle][assetId]`.
+   *
+   * Static, as it was in the legacy modal: transform URLs are stable for an
+   * asset, and modals are constructed per relation field, so sharing the cache
+   * saves a request per field per asset.
+   */
+  static transformUrls: Record<string, Record<number, string | false>> = {};
+
+  #selectedTransform: string | null = null;
+
+  declare readonly options: ElementSelectorController<A>['options'] &
+    AssetSelectorOptions;
+
+  constructor(options: AssetSelectorOptions) {
+    super(options);
+  }
+
+  get transforms(): readonly AssetTransform[] {
+    return this.options.transforms ?? [];
+  }
+
+  /** Whether the transform menu should be available right now. */
+  get canApplyTransform(): boolean {
+    return this.selection.length > 0 && this.transforms.length > 0;
+  }
+
+  /**
+   * Resolve the transform's URL for every selected asset, then submit.
+   *
+   * Holds `busy` across the fetches, so the chrome shows a spinner and can't be
+   * clicked again mid-flight.
+   */
+  async selectWithTransform(handle: string): Promise<void> {
+    const cache = (AssetSelectorController.transformUrls[handle] ??= {});
+    const missing = this.selection
+      .map((element) => Number(element.id))
+      .filter((id) => cache[id] === undefined);
+
+    if (missing.length > 0) {
+      const fetchUrl =
+        this.options.fetchTransformUrl ?? defaultFetchTransformUrl;
+
+      this.setBusy(true);
+
+      try {
+        // Sequential, matching the legacy modal: transform generation is
+        // expensive server-side and firing a burst of them was deliberate to
+        // avoid.
+        for (const id of missing) {
+          try {
+            cache[id] = await fetchUrl(id, handle);
+          } catch {
+            // A failed transform falls back to the untransformed URL rather
+            // than blocking the selection.
+            cache[id] = false;
+          }
+        }
+      } finally {
+        this.setBusy(false);
+      }
+    }
+
+    this.#selectedTransform = handle;
+
+    try {
+      await this.submit();
+    } finally {
+      this.#selectedTransform = null;
+    }
+  }
+
+  protected override buildElementInfo(
+    selection: readonly ElementInfo[]
+  ): ElementInfo[] {
+    const info = super.buildElementInfo(selection);
+
+    if (!this.#selectedTransform) {
+      return info;
+    }
+
+    const cache =
+      AssetSelectorController.transformUrls[this.#selectedTransform] ?? {};
+
+    for (const item of info) {
+      const url = cache[Number(item.id)];
+
+      if (url !== undefined && url !== false) {
+        item.url = url;
+      }
+    }
+
+    return info;
+  }
+
+  protected override selectMeta(): SelectMeta {
+    return {transform: this.#selectedTransform};
+  }
+}
diff --git a/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts
new file mode 100644
index 00000000000..c1d0c245e1e
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts
@@ -0,0 +1,599 @@
+import {describe, expect, it, vi} from 'vite-plus/test';
+import {ElementSelectorController} from './element-selector-controller.js';
+import type {
+  ElementIndexAdapter,
+  ElementIndexBody,
+  ElementInfo,
+  ElementSelectorOptions,
+} from './types.js';
+
+const ENTRY = 'CraftCms\\Cms\\Entry\\Elements\\Entry';
+
+function element(id: number, extra: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    id,
+    siteId: 1,
+    label: `Element ${id}`,
+    status: 'live',
+    url: `/entry-${id}`,
+    hasThumb: false,
+    ...extra,
+  };
+}
+
+function body(props: Record<string, unknown> = {}): ElementIndexBody {
+  return {html: '<div class="element-index"></div>', props};
+}
+
+function create(options: Partial<ElementSelectorOptions> = {}) {
+  return new ElementSelectorController({
+    elementType: ENTRY,
+    loadIndexBody: async () => body(),
+    ...options,
+  });
+}
+
+function stubIndex() {
+  // `satisfies` rather than an annotation: it checks the shape against the
+  // adapter contract while keeping the Mock types the assertions need.
+  return {
+    clearSelection: vi.fn(),
+    destroy: vi.fn(),
+  } satisfies ElementIndexAdapter;
+}
+
+describe('options', () => {
+  it('falls back to defaults', () => {
+    const controller = create();
+
+    expect(controller.options.bodyAction).toBe('element-selector-modals/body');
+    expect(controller.options.hideOnSelect).toBe(true);
+    expect(controller.options.multiSelect).toBe(false);
+  });
+
+  it('does not let explicitly-undefined keys shadow defaults', () => {
+    // Callers build settings by spreading partials, which routinely produces
+    // `{hideOnSelect: undefined}`.
+    const controller = create({
+      hideOnSelect: undefined,
+      multiSelect: undefined,
+    });
+
+    expect(controller.options.hideOnSelect).toBe(true);
+    expect(controller.options.multiSelect).toBe(false);
+  });
+
+  it('resolves title and select label lazily, not at module load', () => {
+    const controller = create();
+
+    expect(controller.options.modalTitle).toBeTruthy();
+    expect(controller.options.selectBtnLabel).toBeTruthy();
+    expect(create({modalTitle: 'Choose'}).options.modalTitle).toBe('Choose');
+  });
+});
+
+describe('indexParams', () => {
+  it('identifies the index', () => {
+    const controller = create({sources: ['section:a'], condition: {x: 1}});
+
+    expect(controller.indexParams()).toEqual({
+      context: 'modal',
+      elementType: ENTRY,
+      sources: ['section:a'],
+      condition: {x: 1},
+    });
+  });
+
+  it.each([
+    ['null', null, false],
+    ['auto', 'auto' as const, false],
+  ])('omits showSiteMenu when %s', (_label, showSiteMenu, present) => {
+    expect('showSiteMenu' in create({showSiteMenu}).indexParams()).toBe(
+      present
+    );
+  });
+
+  it.each([
+    [true, '1'],
+    [false, '0'],
+  ])('serializes showSiteMenu %s as %s', (showSiteMenu, expected) => {
+    expect(create({showSiteMenu}).indexParams().showSiteMenu).toBe(expected);
+  });
+
+  it('includes siteIds only when set', () => {
+    expect('siteIds' in create().indexParams()).toBe(false);
+    expect(create({siteIds: [1, 2]}).indexParams().siteIds).toEqual([1, 2]);
+  });
+});
+
+describe('selection and canSubmit', () => {
+  it('cannot submit with nothing selected', () => {
+    expect(create().state.canSubmit).toBe(false);
+  });
+
+  it('can submit once something is selected', () => {
+    const controller = create();
+    controller.setSelection([element(1)]);
+
+    expect(controller.state.canSubmit).toBe(true);
+    expect(controller.hasSelection).toBe(true);
+  });
+
+  it('cannot submit while loading', async () => {
+    let release: () => void = () => {};
+    const controller = create({
+      loadIndexBody: () =>
+        new Promise<ElementIndexBody>((resolve) => {
+          release = () => resolve(body());
+        }),
+    });
+
+    const pending = controller.reload();
+    controller.setSelection([element(1)]);
+    expect(controller.state.loading).toBe(true);
+    expect(controller.state.canSubmit).toBe(false);
+
+    release();
+    await pending;
+    expect(controller.state.canSubmit).toBe(true);
+  });
+
+  it('emits change when the selection changes', () => {
+    const controller = create();
+    const seen: number[] = [];
+    controller.on('change', (state) => seen.push(state.selection.length));
+
+    controller.setSelection([element(1)]);
+    controller.setSelection([]);
+
+    expect(seen).toEqual([1, 0]);
+  });
+
+  it('hands out a frozen snapshot rather than live internals', () => {
+    const controller = create();
+    controller.setSelection([element(1)]);
+
+    const {state} = controller;
+    expect(Object.isFrozen(state)).toBe(true);
+    controller.setSelection([element(1), element(2)]);
+    expect(state.selection).toHaveLength(1);
+    expect(controller.state.selection).toHaveLength(2);
+  });
+});
+
+describe('busy', () => {
+  it('is held for the duration of an async onSelect', async () => {
+    let release: () => void = () => {};
+    const controller = create({
+      hideOnSelect: false,
+      onSelect: () =>
+        new Promise<void>((resolve) => {
+          release = resolve;
+        }),
+    });
+    controller.setSelection([element(1)]);
+
+    const pending = controller.submit();
+    expect(controller.state.busy).toBe(true);
+    expect(controller.state.canSubmit).toBe(false);
+    expect(controller.state.canCancel).toBe(false);
+
+    release();
+    await pending;
+
+    expect(controller.state.busy).toBe(false);
+    expect(controller.state.canCancel).toBe(true);
+  });
+
+  it('is released when onSelect throws', async () => {
+    // The old modal disabled four things by hand and re-enabled them only on
+    // the success path, so a throw left the chrome stuck for good.
+    const controller = create({
+      onSelect: () => Promise.reject(new Error('render-elements failed')),
+    });
+    const errors: Error[] = [];
+    controller.on('error', (error) => errors.push(error));
+    controller.setSelection([element(1)]);
+
+    await controller.submit();
+
+    expect(controller.state.busy).toBe(false);
+    expect(controller.state.canCancel).toBe(true);
+    expect(errors.map((e) => e.message)).toEqual(['render-elements failed']);
+    expect(controller.state.error?.message).toBe('render-elements failed');
+  });
+
+  it('ignores a second submit while one is in flight', async () => {
+    let release: () => void = () => {};
+    const onSelect = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          release = resolve;
+        })
+    );
+    const controller = create({hideOnSelect: false, onSelect});
+    controller.setSelection([element(1)]);
+
+    const first = controller.submit();
+    await controller.submit();
+    release();
+    await first;
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('submit', () => {
+  it('does nothing with an empty selection', async () => {
+    const onSelect = vi.fn();
+    await create({onSelect}).submit();
+
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it('hands the selection to onSelect and emits select', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    const selected: ElementInfo[][] = [];
+    controller.on('select', ({elements}) => selected.push(elements));
+
+    controller.setSelection([element(1), element(2)]);
+    await controller.submit();
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect.mock.calls[0]![0].map((e: ElementInfo) => e.id)).toEqual([
+      1, 2,
+    ]);
+    expect(selected[0]!.map((e) => e.id)).toEqual([1, 2]);
+  });
+
+  it('preserves extra row data such as kind and alt', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.setSelection([element(1, {kind: 'image', alt: 'A cat'})]);
+
+    await controller.submit();
+
+    expect(onSelect.mock.calls[0]![0][0]).toMatchObject({
+      kind: 'image',
+      alt: 'A cat',
+    });
+  });
+
+  it('copies elements rather than handing out the internal objects', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    const original = element(1);
+    controller.setSelection([original]);
+
+    await controller.submit();
+
+    expect(onSelect.mock.calls[0]![0][0]).not.toBe(original);
+  });
+
+  it('closes when hideOnSelect is set', async () => {
+    const controller = create({hideOnSelect: true});
+    await controller.open();
+    controller.setSelection([element(1)]);
+
+    await controller.submit();
+
+    expect(controller.state.open).toBe(false);
+  });
+
+  it('stays open when hideOnSelect is off', async () => {
+    const controller = create({hideOnSelect: false});
+    await controller.open();
+    controller.setSelection([element(1)]);
+
+    await controller.submit();
+
+    expect(controller.state.open).toBe(true);
+  });
+
+  describe('disableElementsOnSelect', () => {
+    it('adds the selection to the disabled set and clears the index', async () => {
+      const controller = create({
+        disableElementsOnSelect: true,
+        hideOnSelect: false,
+      });
+      const index = stubIndex();
+      controller.attachIndex(index);
+      controller.setSelection([element(1), element(2)]);
+
+      await controller.submit();
+
+      expect(controller.state.disabledElementIds).toEqual([1, 2]);
+      expect(index.clearSelection).toHaveBeenCalled();
+    });
+
+    it('accumulates across submissions without duplicating', async () => {
+      const controller = create({
+        disableElementsOnSelect: true,
+        hideOnSelect: false,
+        disabledElementIds: [9],
+      });
+      controller.setSelection([element(1)]);
+      await controller.submit();
+      controller.setSelection([element(1), element(2)]);
+      await controller.submit();
+
+      expect(controller.state.disabledElementIds).toEqual([9, 1, 2]);
+    });
+
+    it('leaves the disabled set alone when off', async () => {
+      const controller = create({hideOnSelect: false});
+      controller.setSelection([element(1)]);
+
+      await controller.submit();
+
+      expect(controller.state.disabledElementIds).toEqual([]);
+    });
+  });
+});
+
+describe('cancel', () => {
+  it('fires onCancel and closes', async () => {
+    // The legacy modal declared `onCancel` and never called it.
+    const onCancel = vi.fn();
+    const controller = create({onCancel});
+    await controller.open();
+
+    controller.cancel();
+
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(controller.state.open).toBe(false);
+  });
+
+  it('emits cancel', async () => {
+    const controller = create();
+    const seen = vi.fn();
+    controller.on('cancel', seen);
+    await controller.open();
+
+    controller.cancel();
+
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it('is refused while busy', async () => {
+    const onCancel = vi.fn();
+    const controller = create({
+      onCancel,
+      hideOnSelect: false,
+      onSelect: () => new Promise<void>(() => {}),
+    });
+    await controller.open();
+    controller.setSelection([element(1)]);
+    void controller.submit();
+
+    controller.cancel();
+
+    expect(onCancel).not.toHaveBeenCalled();
+    expect(controller.state.open).toBe(true);
+  });
+});
+
+describe('setDisabledElementIds', () => {
+  it('emits change, so a bound index re-reads it', () => {
+    // The old modal assigned to a settings array the index had already copied
+    // by value, so the index never saw the new set.
+    const controller = create();
+    const seen: readonly number[][] = [];
+    controller.on('change', (state) =>
+      (seen as number[][]).push([...state.disabledElementIds])
+    );
+
+    controller.setDisabledElementIds([3, 4]);
+
+    expect(seen).toEqual([[3, 4]]);
+    expect(controller.state.disabledElementIds).toEqual([3, 4]);
+  });
+
+  it('de-duplicates and coerces to numbers', () => {
+    const controller = create();
+    controller.setDisabledElementIds([1, 1, 2, '3' as unknown as number]);
+
+    expect(controller.state.disabledElementIds).toEqual([1, 2, 3]);
+  });
+
+  it('seeds from options', () => {
+    expect(create({disabledElementIds: [5]}).state.disabledElementIds).toEqual([
+      5,
+    ]);
+  });
+
+  it('does not mutate the caller’s array', async () => {
+    const ids = [1];
+    const controller = create({
+      disabledElementIds: ids,
+      disableElementsOnSelect: true,
+      hideOnSelect: false,
+    });
+    controller.setSelection([element(2)]);
+
+    await controller.submit();
+
+    expect(ids).toEqual([1]);
+  });
+});
+
+describe('open and close', () => {
+  it('loads the index body once', async () => {
+    const loadIndexBody = vi.fn(async () => body({total: 3}));
+    const controller = create({loadIndexBody});
+
+    await controller.open();
+    controller.close();
+    await controller.open();
+
+    expect(loadIndexBody).toHaveBeenCalledTimes(1);
+    expect(controller.state.indexBody?.props).toEqual({total: 3});
+  });
+
+  it('passes the action and params to the loader', async () => {
+    const loadIndexBody = vi.fn(async () => body());
+    const controller = create({
+      loadIndexBody,
+      bodyAction: 'custom/body',
+      sources: ['section:a'],
+    });
+
+    await controller.open();
+
+    expect(loadIndexBody).toHaveBeenCalledWith('custom/body', {
+      context: 'modal',
+      elementType: ENTRY,
+      sources: ['section:a'],
+      condition: undefined,
+    });
+  });
+
+  it('clears the selection on reopen but keeps disabled ids', async () => {
+    // The relation field caches one instance and reopens it. A surviving
+    // selection would leave Select enabled before the user picked anything.
+    const controller = create({disabledElementIds: [7]});
+    const index = stubIndex();
+    controller.attachIndex(index);
+    await controller.open();
+    controller.setSelection([element(1)]);
+    controller.close();
+
+    await controller.open();
+
+    expect(controller.state.selection).toEqual([]);
+    expect(controller.state.canSubmit).toBe(false);
+    expect(index.clearSelection).toHaveBeenCalled();
+    expect(controller.state.disabledElementIds).toEqual([7]);
+  });
+
+  it('keeps the selection through close, so a submit handler can still read it', async () => {
+    const controller = create();
+    await controller.open();
+    controller.setSelection([element(1)]);
+
+    controller.close();
+
+    expect(controller.state.selection).toHaveLength(1);
+  });
+
+  it('emits open and close once each', async () => {
+    const controller = create();
+    const events: string[] = [];
+    controller.on('open', () => events.push('open'));
+    controller.on('close', () => events.push('close'));
+
+    await controller.open();
+    await controller.open();
+    controller.close();
+    controller.close();
+
+    expect(events).toEqual(['open', 'close']);
+  });
+
+  it('fires onClose when closing', async () => {
+    const onClose = vi.fn();
+    const controller = create({onClose});
+    await controller.open();
+
+    controller.close();
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('records a load failure without throwing', async () => {
+    const controller = create({
+      loadIndexBody: async () => {
+        throw new Error('nope');
+      },
+    });
+
+    await controller.open();
+
+    expect(controller.state.error?.message).toBe('nope');
+    expect(controller.state.loading).toBe(false);
+    expect(controller.state.indexBody).toBeNull();
+  });
+});
+
+describe('destroy', () => {
+  it('tears down the adapter and stops emitting', async () => {
+    const controller = create();
+    const index = stubIndex();
+    const seen = vi.fn();
+    controller.attachIndex(index);
+    controller.on('change', seen);
+    await controller.open();
+    seen.mockClear();
+
+    controller.destroy();
+    const changesDuringDestroy = seen.mock.calls.length;
+    controller.setSelection([element(1)]);
+
+    expect(index.destroy).toHaveBeenCalled();
+    expect(controller.index).toBeNull();
+    expect(controller.state.open).toBe(false);
+    expect(seen.mock.calls.length).toBe(changesDuringDestroy);
+  });
+});
+
+describe('listeners', () => {
+  it('unsubscribes through the returned function', () => {
+    const controller = create();
+    const seen = vi.fn();
+    const off = controller.on('change', seen);
+
+    controller.setSelection([element(1)]);
+    off();
+    controller.setSelection([]);
+
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it('survives a listener unsubscribing itself mid-emit', () => {
+    const controller = create();
+    const order: string[] = [];
+    const off = controller.on('change', () => {
+      order.push('first');
+      off();
+    });
+    controller.on('change', () => order.push('second'));
+
+    controller.setSelection([element(1)]);
+
+    expect(order).toEqual(['first', 'second']);
+  });
+});
+
+describe('indexSettings', () => {
+  it('carries the query and selection configuration', () => {
+    const controller = create({
+      storageKey: 'field-1',
+      criteria: {status: 'live'},
+      multiSelect: true,
+      disabledElementIds: [4],
+    });
+
+    expect(controller.indexSettings()).toMatchObject({
+      context: 'modal',
+      storageKey: 'field-1',
+      criteria: {status: 'live'},
+      multiSelect: true,
+      selectable: true,
+      disabledElementIds: [4],
+    });
+  });
+
+  it('lets indexSettings overrides win', () => {
+    const controller = create({indexSettings: {multiSelect: 'overridden'}});
+
+    expect(controller.indexSettings().multiSelect).toBe('overridden');
+  });
+
+  it('reflects the current disabled set, not the initial one', () => {
+    const controller = create({disabledElementIds: [1]});
+    controller.setDisabledElementIds([2, 3]);
+
+    expect(controller.indexSettings().disabledElementIds).toEqual([2, 3]);
+  });
+});
diff --git a/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts
new file mode 100644
index 00000000000..8eae1c89706
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts
@@ -0,0 +1,426 @@
+import {actionClient} from '@src/utilities/api/actionClient.js';
+import {t} from '@src/utilities/translate.js';
+import type {
+  ElementIndexAdapter,
+  ElementIndexBody,
+  ElementInfo,
+  ElementSelectorEvent,
+  ElementSelectorEventMap,
+  ElementSelectorListener,
+  ElementSelectorOptions,
+  ElementSelectorState,
+  LoadIndexBody,
+  ResolvedElementSelectorOptions,
+  SelectMeta,
+} from './types.js';
+
+const defaultLoadIndexBody: LoadIndexBody = async (action, params) => {
+  // A bare action path is fine: `actionClient`'s request interceptor expands it
+  // against the runtime CP trigger, so there is no `Craft.getActionUrl` here.
+  const {data} = await actionClient.post(action, params);
+
+  return data as ElementIndexBody;
+};
+
+/**
+ * The element selector's business logic, with no rendering concerns.
+ *
+ * Owns selection state, the rules about what may be selected, the index request
+ * parameters, and the shape of the payload handed back to the opener. A
+ * presentation layer binds to it by subscribing to `change` and reading
+ * {@link state}; user intent goes back in through {@link submit}, {@link cancel}
+ * and {@link setSelection}. Nothing flows the other way, which is what keeps a
+ * web component and a Vue component from drifting apart.
+ *
+ * @example
+ * const controller = new ElementSelectorController({
+ *   elementType: 'CraftCms\\Cms\\Entry\\Elements\\Entry',
+ *   onSelect: (elements) => console.log(elements),
+ * });
+ *
+ * controller.on('change', (state) => render(state));
+ * await controller.open();
+ */
+export class ElementSelectorController<
+  A extends ElementIndexAdapter = ElementIndexAdapter,
+> {
+  static readonly defaults = {
+    multiSelect: false,
+    disabledElementIds: [] as number[],
+    disableElementsOnSelect: false,
+    hideOnSelect: true,
+    showTitle: false,
+    fullscreen: false,
+    bodyAction: 'element-selector-modals/body',
+    indexSettings: {} as Record<string, unknown>,
+    preferStoredSource: false,
+    showSourcePath: true,
+    hideSidebar: false,
+  };
+
+  readonly options: ResolvedElementSelectorOptions;
+
+  #index: A | null = null;
+  #selection: ElementInfo[] = [];
+  #disabledElementIds: number[] = [];
+  #indexBody: ElementIndexBody | null = null;
+  #open = false;
+  #loading = false;
+  #busy = false;
+  #error: Error | null = null;
+  #state: ElementSelectorState;
+
+  #listeners = new Map<ElementSelectorEvent, Set<(data: never) => void>>();
+
+  constructor(options: ElementSelectorOptions) {
+    this.options = {
+      ...ElementSelectorController.defaults,
+      // Resolved here rather than at module scope, where the translation
+      // catalogue may not have loaded yet.
+      modalTitle: t('Select element'),
+      selectBtnLabel: t('Select'),
+      ...stripUndefined(options),
+    } as ResolvedElementSelectorOptions;
+
+    this.#disabledElementIds = [...(this.options.disabledElementIds ?? [])];
+    this.#state = this.#buildState();
+  }
+
+  get elementType(): string {
+    return this.options.elementType;
+  }
+
+  get state(): ElementSelectorState {
+    return this.#state;
+  }
+
+  get index(): A | null {
+    return this.#index;
+  }
+
+  get hasSelection(): boolean {
+    return this.#selection.length > 0;
+  }
+
+  // ───────────────────────────── observation ─────────────────────────────
+
+  /** Subscribe to an event. Returns an unsubscribe function. */
+  on<E extends ElementSelectorEvent>(
+    event: E,
+    listener: ElementSelectorListener<E>
+  ): () => void {
+    let set = this.#listeners.get(event);
+
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(event, set);
+    }
+
+    set.add(listener as (data: never) => void);
+
+    return () => {
+      this.#listeners.get(event)?.delete(listener as (data: never) => void);
+    };
+  }
+
+  // ───────────────────────────── lifecycle ──────────────────────────────
+
+  /**
+   * Show the selector, loading the index body the first time.
+   *
+   * Reopening keeps the adapter, the loaded body and `disabledElementIds`, but
+   * clears the selection — openers such as the relation field's element select
+   * input cache one instance and reopen it, and a stale selection would leave
+   * the Select button enabled before the user has picked anything.
+   */
+  async open(): Promise<void> {
+    this.#selection = [];
+    this.#index?.clearSelection();
+
+    if (!this.#open) {
+      this.#open = true;
+      this.#emit('open', undefined);
+    }
+
+    this.#update();
+
+    if (!this.#indexBody) {
+      await this.reload();
+    }
+  }
+
+  /** Hide the selector. Deliberately preserves selection and disabled ids. */
+  close(): void {
+    if (!this.#open) {
+      return;
+    }
+
+    this.#open = false;
+    this.#emit('close', undefined);
+    this.options.onClose?.();
+    this.#update();
+  }
+
+  destroy(): void {
+    this.#index?.destroy?.();
+    this.#index = null;
+    this.#selection = [];
+    this.#indexBody = null;
+    this.#open = false;
+    this.#update();
+    this.#listeners.clear();
+  }
+
+  /** (Re)fetch the index body. */
+  async reload(): Promise<void> {
+    const load = this.options.loadIndexBody ?? defaultLoadIndexBody;
+
+    this.#loading = true;
+    this.#error = null;
+    this.#update();
+
+    try {
+      this.#indexBody = await load(this.options.bodyAction, this.indexParams());
+    } catch (error) {
+      this.#fail(error);
+    } finally {
+      this.#loading = false;
+      this.#update();
+    }
+  }
+
+  // ─────────────────────────────── intent ───────────────────────────────
+
+  /**
+   * Hand the current selection to the opener.
+   *
+   * Holds `busy` until `onSelect` settles, so a slow or failing handler can't be
+   * raced by a second click and can't leave the chrome stuck.
+   */
+  async submit(): Promise<void> {
+    if (!this.#state.canSubmit) {
+      return;
+    }
+
+    const elements = this.buildElementInfo(this.#selection);
+    const meta = this.selectMeta();
+
+    this.#busy = true;
+    this.#update();
+
+    try {
+      this.#emit('select', {elements, meta});
+      await this.options.onSelect?.(elements, meta);
+    } catch (error) {
+      this.#fail(error);
+      return;
+    } finally {
+      this.#busy = false;
+      this.#update();
+    }
+
+    if (this.options.disableElementsOnSelect) {
+      this.setDisabledElementIds([
+        ...this.#disabledElementIds,
+        ...elements.map((element) => Number(element.id)),
+      ]);
+      this.#index?.clearSelection();
+    }
+
+    if (this.options.hideOnSelect) {
+      this.close();
+    }
+  }
+
+  cancel(): void {
+    if (!this.#state.canCancel) {
+      return;
+    }
+
+    this.#emit('cancel', undefined);
+    this.options.onCancel?.();
+    this.close();
+  }
+
+  // ──────────────────────────── from the index ───────────────────────────
+
+  attachIndex(adapter: A): void {
+    this.#index = adapter;
+    this.#update();
+  }
+
+  detachIndex(): void {
+    this.#index = null;
+    this.#update();
+  }
+
+  setSelection(elements: ElementInfo[]): void {
+    this.#selection = [...elements];
+    this.#update();
+  }
+
+  // ─────────────────────────── from the opener ───────────────────────────
+
+  /**
+   * Replace the set of elements that may not be selected.
+   *
+   * A whole-set assignment rather than add/remove calls, because that is how the
+   * relation field thinks about it — and because pushing the new set through
+   * `change` is what keeps the index in sync. The old modal mutated a settings
+   * array that had already been copied into the index by value, so the index
+   * never saw the update.
+   */
+  setDisabledElementIds(ids: number[]): void {
+    this.#disabledElementIds = [...new Set(ids.map(Number))];
+    this.#update();
+  }
+
+  /** Escape hatch for openers doing async work outside `onSelect`. */
+  setBusy(busy: boolean): void {
+    this.#busy = busy;
+    this.#update();
+  }
+
+  // ─────────────────────────── index bootstrapping ───────────────────────
+
+  /** Identifies the index to the server. */
+  indexParams(): Record<string, unknown> {
+    const {options} = this;
+
+    const params: Record<string, unknown> = {
+      context: 'modal',
+      elementType: this.elementType,
+      sources: options.sources,
+      condition: options.condition,
+    };
+
+    // `null` and `'auto'` both mean "server decides", so the key is omitted.
+    if (options.showSiteMenu != null && options.showSiteMenu !== 'auto') {
+      params.showSiteMenu = options.showSiteMenu ? '1' : '0';
+    }
+
+    if (options.siteIds) {
+      params.siteIds = options.siteIds;
+    }
+
+    return params;
+  }
+
+  /** Configuration for the index itself, as opposed to the request that loads it. */
+  indexSettings(): Record<string, unknown> {
+    const {options} = this;
+
+    return {
+      context: 'modal',
+      storageKey: options.storageKey,
+      condition: options.condition,
+      referenceElementId: options.referenceElementId,
+      referenceElementOwnerId: options.referenceElementOwnerId,
+      referenceElementSiteId: options.referenceElementSiteId,
+      criteria: {...options.criteria},
+      disabledElementIds: [...this.#disabledElementIds],
+      selectable: true,
+      multiSelect: options.multiSelect,
+      waitForDoubleClicks: true,
+      hideSidebar: options.hideSidebar,
+      defaultSiteId: options.defaultSiteId,
+      defaultSource: options.defaultSource,
+      defaultSourcePath: options.defaultSourcePath,
+      preferStoredSource: options.preferStoredSource,
+      showSourcePath: options.showSourcePath,
+      ...options.indexSettings,
+    };
+  }
+
+  // ────────────────────────── subclass hooks ────────────────────────────
+
+  /** Whether the current selection may be submitted. */
+  protected canSubmitSelection(): boolean {
+    return this.#selection.length > 0;
+  }
+
+  /** Shapes the payload handed to `onSelect`. */
+  protected buildElementInfo(selection: readonly ElementInfo[]): ElementInfo[] {
+    return selection.map((element) => ({...element}));
+  }
+
+  /** Extra context accompanying a selection. */
+  protected selectMeta(): SelectMeta {
+    return {};
+  }
+
+  /** For subclasses that keep their own derived state in sync. */
+  protected notifyChange(): void {
+    this.#update();
+  }
+
+  /** Read access to the raw selection for subclasses. */
+  protected get selection(): readonly ElementInfo[] {
+    return this.#selection;
+  }
+
+  protected get disabledElementIds(): readonly number[] {
+    return this.#disabledElementIds;
+  }
+
+  // ─────────────────────────────── internals ─────────────────────────────
+
+  #buildState(): ElementSelectorState {
+    const busy = this.#busy;
+    const loading = this.#loading;
+
+    return Object.freeze({
+      open: this.#open,
+      loading,
+      busy,
+      selection: Object.freeze([...this.#selection]),
+      disabledElementIds: Object.freeze([...this.#disabledElementIds]),
+      indexBody: this.#indexBody,
+      error: this.#error,
+      title: this.options.modalTitle,
+      showTitle: this.options.showTitle,
+      selectLabel: this.options.selectBtnLabel,
+      canSubmit: !busy && !loading && this.canSubmitSelection(),
+      canCancel: !busy,
+    });
+  }
+
+  #update(): void {
+    this.#state = this.#buildState();
+    this.#emit('change', this.#state);
+  }
+
+  #fail(error: unknown): void {
+    this.#error =
+      error instanceof Error ? error : new Error(String(error ?? 'Unknown'));
+    this.#emit('error', this.#error);
+  }
+
+  #emit<E extends ElementSelectorEvent>(
+    event: E,
+    data: ElementSelectorEventMap[E]
+  ): void {
+    // Copied before iterating: a listener that unsubscribes itself (or another)
+    // would otherwise mutate the set mid-iteration.
+    const listeners = this.#listeners.get(event);
+
+    if (listeners) {
+      [...listeners].forEach((listener) =>
+        (listener as (value: ElementSelectorEventMap[E]) => void)(data)
+      );
+    }
+  }
+}
+
+/**
+ * Drops explicitly-`undefined` keys so they don't shadow defaults.
+ *
+ * Callers build settings blobs by spreading partial objects, which routinely
+ * yields `{hideOnSelect: undefined}`; a plain spread would overwrite the default
+ * with `undefined` rather than leaving it alone.
+ */
+function stripUndefined<T extends object>(source: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(source).filter(([, value]) => value !== undefined)
+  ) as Partial<T>;
+}
diff --git a/packages/craftcms-ui/src/core/element-selector/index.ts b/packages/craftcms-ui/src/core/element-selector/index.ts
new file mode 100644
index 00000000000..cb42792c708
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/index.ts
@@ -0,0 +1,36 @@
+export {ElementSelectorController} from './element-selector-controller.js';
+export {
+  AssetSelectorController,
+  type AssetSelectorOptions,
+  type AssetTransform,
+  type FetchTransformUrl,
+} from './asset-selector-controller.js';
+export {
+  ASSET_ELEMENT_TYPE,
+  VolumeFolderSelectorController,
+  type SourcePathSegment,
+  type VolumeFolderIndexAdapter,
+  type VolumeFolderSelectorOptions,
+} from './volume-folder-selector-controller.js';
+export {
+  adoptLegacyRegistrations,
+  createElementSelectorController,
+  elementSelectorControllerClass,
+  hasElementSelectorController,
+  registerElementSelectorController,
+  resetElementSelectorControllers,
+  type ElementSelectorControllerClass,
+} from './registry.js';
+export type {
+  ElementIndexAdapter,
+  ElementIndexBody,
+  ElementInfo,
+  ElementSelectorEvent,
+  ElementSelectorEventMap,
+  ElementSelectorListener,
+  ElementSelectorOptions,
+  ElementSelectorState,
+  LoadIndexBody,
+  ResolvedElementSelectorOptions,
+  SelectMeta,
+} from './types.js';
diff --git a/packages/craftcms-ui/src/core/element-selector/registry.test.ts b/packages/craftcms-ui/src/core/element-selector/registry.test.ts
new file mode 100644
index 00000000000..69b2acb9d10
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/registry.test.ts
@@ -0,0 +1,105 @@
+import {afterEach, beforeEach, describe, expect, it} from 'vite-plus/test';
+import {ElementSelectorController} from './element-selector-controller.js';
+import {AssetSelectorController} from './asset-selector-controller.js';
+import {
+  adoptLegacyRegistrations,
+  createElementSelectorController,
+  elementSelectorControllerClass,
+  hasElementSelectorController,
+  registerElementSelectorController,
+  resetElementSelectorControllers,
+} from './registry.js';
+
+const ENTRY = 'CraftCms\\Cms\\Entry\\Elements\\Entry';
+const ASSET = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
+
+class CustomController extends ElementSelectorController {}
+
+beforeEach(() => resetElementSelectorControllers());
+afterEach(() => {
+  resetElementSelectorControllers();
+  delete (globalThis as any).window;
+});
+
+describe('registration', () => {
+  it('falls back to the base controller for an unregistered type', () => {
+    expect(elementSelectorControllerClass(ENTRY)).toBe(
+      ElementSelectorController
+    );
+    expect(hasElementSelectorController(ENTRY)).toBe(false);
+  });
+
+  it('returns the registered class', () => {
+    registerElementSelectorController(ASSET, AssetSelectorController);
+
+    expect(elementSelectorControllerClass(ASSET)).toBe(AssetSelectorController);
+    expect(hasElementSelectorController(ASSET)).toBe(true);
+  });
+
+  it('throws on a duplicate registration', () => {
+    registerElementSelectorController(ASSET, AssetSelectorController);
+
+    expect(() =>
+      registerElementSelectorController(ASSET, CustomController)
+    ).toThrow(/already been registered/);
+  });
+});
+
+describe('createElementSelectorController', () => {
+  it('builds the registered class', () => {
+    registerElementSelectorController(ASSET, AssetSelectorController);
+
+    expect(
+      createElementSelectorController({elementType: ASSET})
+    ).toBeInstanceOf(AssetSelectorController);
+  });
+
+  it('builds the base controller otherwise', () => {
+    const controller = createElementSelectorController({elementType: ENTRY});
+
+    expect(controller).toBeInstanceOf(ElementSelectorController);
+    expect(controller.elementType).toBe(ENTRY);
+  });
+
+  it('passes the options through', () => {
+    const controller = createElementSelectorController({
+      elementType: ENTRY,
+      multiSelect: true,
+    });
+
+    expect(controller.options.multiSelect).toBe(true);
+  });
+});
+
+describe('adoptLegacyRegistrations', () => {
+  it('is a no-op without a window, so core stays node-testable', () => {
+    expect(() => adoptLegacyRegistrations()).not.toThrow();
+  });
+
+  it('tolerates a missing legacy registry', () => {
+    (globalThis as any).window = {Craft: {}};
+
+    expect(() => adoptLegacyRegistrations()).not.toThrow();
+  });
+
+  it('drains classes a plugin registered before this module loaded', () => {
+    (globalThis as any).window = {
+      Craft: {_elementSelectorModalClasses: {[ENTRY]: CustomController}},
+    };
+
+    adoptLegacyRegistrations();
+
+    expect(elementSelectorControllerClass(ENTRY)).toBe(CustomController);
+  });
+
+  it('leaves an existing modern registration alone', () => {
+    registerElementSelectorController(ASSET, AssetSelectorController);
+    (globalThis as any).window = {
+      Craft: {_elementSelectorModalClasses: {[ASSET]: CustomController}},
+    };
+
+    adoptLegacyRegistrations();
+
+    expect(elementSelectorControllerClass(ASSET)).toBe(AssetSelectorController);
+  });
+});
diff --git a/packages/craftcms-ui/src/core/element-selector/registry.ts b/packages/craftcms-ui/src/core/element-selector/registry.ts
new file mode 100644
index 00000000000..1dae0b30ff6
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/registry.ts
@@ -0,0 +1,80 @@
+import {ElementSelectorController} from './element-selector-controller.js';
+import type {ElementSelectorOptions} from './types.js';
+
+export type ElementSelectorControllerClass = new (
+  options: ElementSelectorOptions
+) => ElementSelectorController<any>;
+
+const controllers = new Map<string, ElementSelectorControllerClass>();
+
+/**
+ * Registers the controller to use for an element type.
+ *
+ * Throws on a second registration for the same type, as the legacy registry did
+ * — two plugins claiming one element type is a conflict worth surfacing, not one
+ * to resolve by last-write-wins.
+ */
+export function registerElementSelectorController(
+  elementType: string,
+  controllerClass: ElementSelectorControllerClass
+): void {
+  if (controllers.has(elementType)) {
+    throw new Error(
+      `An element selector controller has already been registered for the element type “${elementType}”.`
+    );
+  }
+
+  controllers.set(elementType, controllerClass);
+}
+
+export function hasElementSelectorController(elementType: string): boolean {
+  return controllers.has(elementType);
+}
+
+/** The controller registered for an element type, or the base controller. */
+export function elementSelectorControllerClass(
+  elementType: string
+): ElementSelectorControllerClass {
+  return controllers.get(elementType) ?? ElementSelectorController;
+}
+
+export function createElementSelectorController(
+  options: ElementSelectorOptions
+): ElementSelectorController<any> {
+  return new (elementSelectorControllerClass(options.elementType))(options);
+}
+
+/**
+ * Takes over anything sitting on the legacy `Craft._elementSelectorModalClasses`.
+ *
+ * The legacy bundle is a plain script that runs before this module, so a plugin
+ * can have registered before there was anywhere modern to put it. Existing
+ * modern entries win — a type registered here already is left alone.
+ *
+ * The `window` guard keeps this file importable under the `node` test
+ * environment, which is what enforces that the rest of `core/` stays DOM-free.
+ */
+export function adoptLegacyRegistrations(): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const legacy = (window as any).Craft?._elementSelectorModalClasses as
+    | Record<string, ElementSelectorControllerClass>
+    | undefined;
+
+  if (!legacy) {
+    return;
+  }
+
+  for (const [elementType, controllerClass] of Object.entries(legacy)) {
+    if (!controllers.has(elementType)) {
+      controllers.set(elementType, controllerClass);
+    }
+  }
+}
+
+/** Test seam. */
+export function resetElementSelectorControllers(): void {
+  controllers.clear();
+}
diff --git a/packages/craftcms-ui/src/core/element-selector/types.ts b/packages/craftcms-ui/src/core/element-selector/types.ts
new file mode 100644
index 00000000000..80de4f846a5
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/types.ts
@@ -0,0 +1,174 @@
+/**
+ * Types for the element selector core.
+ *
+ * This folder is deliberately free of `lit`, `vue`, `jquery` and the `Craft`
+ * global — it is the business layer both the web component and the Vue modal
+ * bind to, and third-party code can drive it directly. The `core` vitest project
+ * runs on the `node` environment to keep that honest.
+ */
+
+/**
+ * What a selection hands back.
+ *
+ * The six named keys are the stable contract, produced by
+ * `ModalIndexViewModel::extraRowData()` on the server. The index signature
+ * carries whatever else that method emits for a given element type — `kind` and
+ * `alt` for assets, `folderId` for folders — so a consumer that needs more than
+ * the common six gets it without a change here.
+ */
+export interface ElementInfo {
+  id: number;
+  siteId: number | null;
+  label: string;
+  status: string | null;
+  url: string | null;
+  hasThumb: boolean;
+  [key: string]: unknown;
+}
+
+/** The `element-selector-modals/body` response. */
+export interface ElementIndexBody {
+  /** Legacy `ElementIndexHtml` markup. Only the volume-folder path reads it. */
+  html: string;
+  /** `ModalIndexViewModel::toArray()`. The Vue index reads it. */
+  props: Record<string, unknown>;
+}
+
+/** Loads the index payload. Injectable so the core is testable without axios. */
+export type LoadIndexBody = (
+  action: string,
+  params: Record<string, unknown>
+) => Promise<ElementIndexBody>;
+
+/**
+ * The seam between the controller and whatever is rendering the index.
+ *
+ * The adapter *pushes* selection in via {@link ElementSelectorController.setSelection};
+ * the controller only ever asks it to clear or tear down. That direction is what
+ * lets one controller drive a Vue index, a legacy jQuery index, or a test stub
+ * without knowing which it has.
+ */
+export interface ElementIndexAdapter {
+  clearSelection(): void;
+  destroy?(): void;
+}
+
+/** Extra information about a selection, beyond the elements themselves. */
+export interface SelectMeta {
+  /** Set by `AssetSelectorController` when a transform was chosen. */
+  transform?: string | null;
+}
+
+export interface ElementSelectorOptions {
+  /** Fully-qualified element class, e.g. `CraftCms\Cms\Entry\Elements\Entry`. */
+  elementType: string;
+
+  // — Query —
+  sources?: string[] | null;
+  condition?: unknown;
+  criteria?: Record<string, unknown> | null;
+  referenceElementId?: number | null;
+  referenceElementOwnerId?: number | null;
+  referenceElementSiteId?: number | null;
+  /** `null` or `'auto'` leaves the decision to the server. */
+  showSiteMenu?: boolean | 'auto' | null;
+  siteIds?: number[] | null;
+
+  // — Selection rules —
+  multiSelect?: boolean;
+  disabledElementIds?: number[];
+  /** Add each selection to the disabled set, so it can't be picked twice. */
+  disableElementsOnSelect?: boolean;
+  hideOnSelect?: boolean;
+
+  // — Copy the chrome renders —
+  modalTitle?: string | null;
+  showTitle?: boolean;
+  selectBtnLabel?: string | null;
+  fullscreen?: boolean;
+
+  // — Index bootstrapping —
+  bodyAction?: string;
+  storageKey?: string | null;
+  indexSettings?: Record<string, unknown>;
+  defaultSiteId?: number | null;
+  defaultSource?: string | null;
+  defaultSourcePath?: unknown[] | null;
+  preferStoredSource?: boolean;
+  showSourcePath?: boolean;
+  hideSidebar?: boolean;
+
+  /**
+   * Called with the chosen elements.
+   *
+   * May return a promise. The controller awaits it and holds `busy` for its
+   * duration, which is what replaced the old `disable()` / `disableCancelBtn()` /
+   * `disableSelectBtn()` / `showFooterSpinner()` quartet — and, unlike that
+   * quartet, releases on a throw instead of stranding the buttons.
+   */
+  onSelect?: (
+    elements: ElementInfo[],
+    meta: SelectMeta
+  ) => void | Promise<void>;
+  onCancel?: () => void;
+  onClose?: () => void;
+
+  /** Test seam; defaults to a POST through `actionClient`. */
+  loadIndexBody?: LoadIndexBody;
+}
+
+/** Every option resolved against its default. */
+export type ResolvedElementSelectorOptions = ElementSelectorOptions &
+  Required<
+    Pick<
+      ElementSelectorOptions,
+      | 'multiSelect'
+      | 'disabledElementIds'
+      | 'disableElementsOnSelect'
+      | 'hideOnSelect'
+      | 'showTitle'
+      | 'fullscreen'
+      | 'bodyAction'
+      | 'indexSettings'
+      | 'preferStoredSource'
+      | 'showSourcePath'
+      | 'hideSidebar'
+    >
+  > & {
+    modalTitle: string;
+    selectBtnLabel: string;
+  };
+
+/** An immutable snapshot. A fresh one is built for every `change` event. */
+export interface ElementSelectorState {
+  readonly open: boolean;
+  /** An index body request is in flight. */
+  readonly loading: boolean;
+  /** A submit is in flight; both footer buttons are unavailable. */
+  readonly busy: boolean;
+  readonly selection: readonly ElementInfo[];
+  readonly disabledElementIds: readonly number[];
+  readonly indexBody: ElementIndexBody | null;
+  readonly error: Error | null;
+  readonly title: string;
+  readonly showTitle: boolean;
+  readonly selectLabel: string;
+  readonly canSubmit: boolean;
+  readonly canCancel: boolean;
+}
+
+export interface ElementSelectorEventMap {
+  /** Any state change. The only event a presentation layer needs. */
+  change: ElementSelectorState;
+  open: void;
+  close: void;
+  cancel: void;
+  select: {elements: ElementInfo[]; meta: SelectMeta};
+  error: Error;
+}
+
+export type ElementSelectorEvent = keyof ElementSelectorEventMap;
+
+export type ElementSelectorListener<E extends ElementSelectorEvent> = (
+  data: ElementSelectorEventMap[E]
+) => void;
diff --git a/packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.test.ts b/packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.test.ts
new file mode 100644
index 00000000000..5fb2a471b6f
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.test.ts
@@ -0,0 +1,142 @@
+import {describe, expect, it, vi} from 'vite-plus/test';
+import {
+  ASSET_ELEMENT_TYPE,
+  VolumeFolderSelectorController,
+} from './volume-folder-selector-controller.js';
+import type {
+  SourcePathSegment,
+  VolumeFolderIndexAdapter,
+  VolumeFolderSelectorOptions,
+} from './volume-folder-selector-controller.js';
+import type {ElementInfo} from './types.js';
+
+function create(options: Partial<VolumeFolderSelectorOptions> = {}) {
+  return new VolumeFolderSelectorController({
+    hideOnSelect: false,
+    loadIndexBody: async () => ({html: '', props: {}}),
+    ...options,
+  });
+}
+
+/** Stands in for the legacy jQuery index, which owns the breadcrumb. */
+function folderIndex(
+  sourcePath: SourcePathSegment[]
+): VolumeFolderIndexAdapter {
+  return {
+    sourcePath,
+    clearSelection: vi.fn(),
+    destroy: vi.fn(),
+  };
+}
+
+function folderRow(folderId: number): ElementInfo {
+  return {
+    id: 900 + folderId,
+    folderId,
+    siteId: null,
+    label: `Folder ${folderId}`,
+    status: null,
+    url: null,
+    hasThumb: false,
+  };
+}
+
+describe('configuration', () => {
+  it('is always the asset element type', () => {
+    expect(create().elementType).toBe(ASSET_ELEMENT_TYPE);
+  });
+
+  it('browses folders only', () => {
+    expect(create().indexParams().foldersOnly).toBe(true);
+    expect(create().indexSettings().foldersOnly).toBe(true);
+  });
+
+  it('never offers the site menu, since folders do not vary by site', () => {
+    expect(create({showSiteMenu: true}).indexParams().showSiteMenu).toBe('0');
+  });
+
+  it('passes disabledFolderIds to the index', () => {
+    expect(create({disabledFolderIds: [3, 4]}).indexSettings()).toMatchObject({
+      disabledFolderIds: [3, 4],
+    });
+  });
+});
+
+describe('selecting a highlighted folder', () => {
+  it('hands back the row’s folderId', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.setSelection([folderRow(12)]);
+
+    await controller.submit();
+
+    expect(onSelect.mock.calls[0]![0]).toHaveLength(1);
+    expect(onSelect.mock.calls[0]![0][0].folderId).toBe(12);
+  });
+});
+
+describe('selecting the open folder', () => {
+  it('can submit with nothing highlighted', () => {
+    // Unreachable in the legacy modal: it gated on
+    // `ev.currentTarget === this.$selectBtn[0]`, but the base bound the click as
+    // a zero-argument arrow, so `ev` was always undefined and Select did nothing.
+    const controller = create();
+    controller.attachIndex(folderIndex([{folderId: 1}, {folderId: 7}]));
+
+    expect(controller.hasSelection).toBe(false);
+    expect(controller.state.canSubmit).toBe(true);
+  });
+
+  it('hands back the deepest breadcrumb folder', async () => {
+    const onSelect = vi.fn();
+    const controller = create({onSelect});
+    controller.attachIndex(
+      folderIndex([
+        {folderId: 1, label: 'Volume'},
+        {folderId: 7, label: 'Nested'},
+      ])
+    );
+
+    await controller.submit();
+
+    expect(onSelect.mock.calls[0]![0][0]).toMatchObject({
+      folderId: 7,
+      label: 'Nested',
+    });
+  });
+
+  it('cannot submit with no index attached', () => {
+    expect(create().state.canSubmit).toBe(false);
+  });
+
+  it('cannot submit with an empty breadcrumb', () => {
+    const controller = create();
+    controller.attachIndex(folderIndex([]));
+
+    expect(controller.state.canSubmit).toBe(false);
+  });
+
+  it('cannot submit when the breadcrumb has no folder id', () => {
+    const controller = create();
+    controller.attachIndex(folderIndex([{label: 'All volumes'}]));
+
+    expect(controller.state.canSubmit).toBe(false);
+  });
+
+  it('refuses a folder in the disabled set', () => {
+    // Moving a folder into itself.
+    const controller = create({disabledFolderIds: [7]});
+    controller.attachIndex(folderIndex([{folderId: 7}]));
+
+    expect(controller.currentFolderId()).toBeNull();
+    expect(controller.state.canSubmit).toBe(false);
+  });
+
+  it('still allows a highlighted row when the open folder is disabled', () => {
+    const controller = create({disabledFolderIds: [7]});
+    controller.attachIndex(folderIndex([{folderId: 7}]));
+    controller.setSelection([folderRow(12)]);
+
+    expect(controller.state.canSubmit).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.ts b/packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.ts
new file mode 100644
index 00000000000..13f66dee73c
--- /dev/null
+++ b/packages/craftcms-ui/src/core/element-selector/volume-folder-selector-controller.ts
@@ -0,0 +1,142 @@
+import {ElementSelectorController} from './element-selector-controller.js';
+import type {
+  ElementIndexAdapter,
+  ElementInfo,
+  ElementSelectorOptions,
+} from './types.js';
+
+export const ASSET_ELEMENT_TYPE = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
+
+/** One step of the breadcrumb into the folder currently open. */
+export interface SourcePathSegment {
+  folderId?: number;
+  label?: string;
+}
+
+/**
+ * A folder index also exposes where it has navigated to.
+ *
+ * That is the whole reason this controller exists: "select the folder I'm
+ * looking at" is a selection the index itself has no row for.
+ */
+export interface VolumeFolderIndexAdapter extends ElementIndexAdapter {
+  readonly sourcePath: readonly SourcePathSegment[];
+}
+
+export interface VolumeFolderSelectorOptions extends Omit<
+  ElementSelectorOptions,
+  'elementType'
+> {
+  /** Folders that may not be chosen — typically the ones being moved. */
+  disabledFolderIds?: number[];
+}
+
+/**
+ * Picks a volume folder rather than an element.
+ *
+ * Browses asset volumes folders-only, and — unlike every other selector — allows
+ * submitting with nothing highlighted, which means "the folder currently open".
+ *
+ * That fallback was unreachable in the legacy modal: it gated on
+ * `ev.currentTarget === this.$selectBtn[0]`, but the base class bound the click
+ * as a zero-argument arrow, so `ev` was always `undefined`. The Select button
+ * would enable and then do nothing. Here the rule lives in
+ * {@link canSubmitSelection} and {@link buildElementInfo}, so the inherited
+ * `submit()` handles both cases with no override and no event to inspect.
+ */
+export class VolumeFolderSelectorController extends ElementSelectorController<VolumeFolderIndexAdapter> {
+  readonly disabledFolderIds: number[];
+
+  constructor(options: VolumeFolderSelectorOptions = {}) {
+    const {disabledFolderIds = [], ...rest} = options;
+
+    super({
+      ...rest,
+      elementType: ASSET_ELEMENT_TYPE,
+      // Folders don't vary by site, so the menu is never useful here.
+      showSiteMenu: false,
+    });
+
+    this.disabledFolderIds = [...disabledFolderIds];
+  }
+
+  override indexParams(): Record<string, unknown> {
+    return {...super.indexParams(), foldersOnly: true};
+  }
+
+  override indexSettings(): Record<string, unknown> {
+    return {
+      ...super.indexSettings(),
+      foldersOnly: true,
+      disabledFolderIds: [...this.disabledFolderIds],
+    };
+  }
+
+  /** The open folder, if it may be selected. */
+  currentFolderId(): number | null {
+    const sourcePath = this.index?.sourcePath;
+
+    if (!sourcePath?.length) {
+      return null;
+    }
+
+    const last = sourcePath[sourcePath.length - 1]!;
+
+    if (last.folderId === undefined) {
+      return null;
+    }
+
+    return this.disabledFolderIds.includes(last.folderId)
+      ? null
+      : last.folderId;
+  }
+
+  protected override canSubmitSelection(): boolean {
+    return super.canSubmitSelection() || this.currentFolderId() !== null;
+  }
+
+  /**
+   * Always `{folderId}`-bearing, whether a row was highlighted or the open
+   * folder is being chosen.
+   *
+   * The legacy modal read `data-folder-id` off each row's DOM; the id now
+   * arrives as extra row data from `ModalIndexViewModel::extraRowData()`.
+   */
+  protected override buildElementInfo(
+    selection: readonly ElementInfo[]
+  ): ElementInfo[] {
+    if (selection.length > 0) {
+      return selection.map((element) => ({
+        ...element,
+        folderId: Number(element.folderId ?? element.id),
+      }));
+    }
+
+    const folderId = this.currentFolderId();
+
+    if (folderId === null) {
+      return [];
+    }
+
+    // Shaped as a full ElementInfo so consumers reading `id`/`label` still work;
+    // `folderId` is the key `AssetIndex` and `MoveAssets` actually read.
+    return [
+      {
+        id: folderId,
+        folderId,
+        siteId: null,
+        label: this.#currentFolderLabel(),
+        status: null,
+        url: null,
+        hasThumb: false,
+      },
+    ];
+  }
+
+  #currentFolderLabel(): string {
+    const sourcePath = this.index?.sourcePath;
+    const last = sourcePath?.[sourcePath.length - 1];
+
+    return last?.label ?? '';
+  }
+}
diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index fa3b9d6edd3..d900fe693cf 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -112,6 +112,7 @@ export * from './utilities/attrs.js';
 export * from './utilities/thumbnail-loader.js';
 export * from './utilities/create.js';
 export * from './utilities/focus-trap.js';
+export * from './core/element-selector/index.js';
 
 // Services
 export {ConfigService} from './services/Config.js';
diff --git a/packages/craftcms-ui/vitest.config.ts b/packages/craftcms-ui/vitest.config.ts
index 95d158a9ed6..d20c50e6b75 100644
--- a/packages/craftcms-ui/vitest.config.ts
+++ b/packages/craftcms-ui/vitest.config.ts
@@ -25,6 +25,18 @@ export default defineConfig({
           environment: 'happy-dom',
         },
       },
+      {
+        resolve: {
+          tsconfigPaths: true,
+        },
+        test: {
+          name: 'core',
+          root: './src/core',
+          // `node`, not happy-dom: the core must not touch the DOM, and running
+          // it without one is what keeps that true.
+          environment: 'node',
+        },
+      },
       {
         resolve: {
           tsconfigPaths: true,

From 2aa57191751860aab32e429d578194d533378ae7 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 21 Aug 2026 17:08:39 -0500
Subject: [PATCH 16/24] Add the element selector modal web component

---
 .../src/components/dialog/dialog.ts           |  31 +-
 .../element-selector-modal/controller-host.ts |  54 +++
 .../element-selector-modal.stories.ts         | 227 ++++++++++++
 .../element-selector-modal.styles.ts          |  98 +++++
 .../element-selector-modal.test.ts            | 348 ++++++++++++++++++
 .../element-selector-modal.ts                 | 254 +++++++++++++
 packages/craftcms-ui/src/index.ts             |   2 +
 7 files changed, 1008 insertions(+), 6 deletions(-)
 create mode 100644 packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts
 create mode 100644 packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.stories.ts
 create mode 100644 packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.styles.ts
 create mode 100644 packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.test.ts
 create mode 100644 packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts

diff --git a/packages/craftcms-ui/src/components/dialog/dialog.ts b/packages/craftcms-ui/src/components/dialog/dialog.ts
index 5ace4f07f54..85d56dd6bfb 100644
--- a/packages/craftcms-ui/src/components/dialog/dialog.ts
+++ b/packages/craftcms-ui/src/components/dialog/dialog.ts
@@ -144,6 +144,7 @@ export default class CraftDialog extends LitElement {
       <dialog
         part="dialog"
         aria-labelledby=${this.titleId}
+        @cancel=${this.#onNativeCancel}
         @close=${this.#onNativeClose}
         @click=${this.#onDialogClick}
       >
@@ -163,7 +164,7 @@ export default class CraftDialog extends LitElement {
           class="close"
           part="close"
           aria-label=${t('Close')}
-          @click=${this.#close}
+          @click=${() => this.requestClose()}
         >
           <craft-icon name="xmark"></craft-icon>
         </button>
@@ -242,8 +243,26 @@ export default class CraftDialog extends LitElement {
     this.dispatchEvent(new CustomEvent(name, {bubbles: true, composed: true}));
   }
 
-  #close = (): void => {
+  /**
+   * A request to dismiss — Escape, the close button, a `data-dialog="close"`
+   * click, or the backdrop.
+   *
+   * Every dismissal path funnels through here so a subclass can route the
+   * intent somewhere else (a controller that may refuse it, say) instead of
+   * intercepting four listeners and the platform's own Escape handling.
+   */
+  protected requestClose(): void {
     this.opened = false;
+  }
+
+  /**
+   * The platform's Escape handling for a modal dialog. Prevented so the close
+   * goes through {@link requestClose} like every other dismissal; the base
+   * implementation then closes it anyway.
+   */
+  #onNativeCancel = (event: Event): void => {
+    event.preventDefault();
+    this.requestClose();
   };
 
   /**
@@ -258,7 +277,7 @@ export default class CraftDialog extends LitElement {
   #onHostKeydown = (event: KeyboardEvent): void => {
     if (this.nonModal && this.opened && event.key === 'Escape') {
       event.preventDefault();
-      this.#close();
+      this.requestClose();
     }
   };
 
@@ -271,20 +290,20 @@ export default class CraftDialog extends LitElement {
     const target = event.target as HTMLElement | null;
 
     if (target?.closest?.('[data-dialog="close"]')) {
-      this.#close();
+      this.requestClose();
     }
   };
 
   /** A click on the backdrop of a modal dialog targets the dialog itself. */
   #onDialogClick = (event: MouseEvent): void => {
     if (this.closeOnOutsideClick && event.target === this.dialogElement) {
-      this.#close();
+      this.requestClose();
     }
   };
 
   #onBackdropClick = (): void => {
     if (this.closeOnOutsideClick) {
-      this.#close();
+      this.requestClose();
     }
   };
 }
diff --git a/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts b/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts
new file mode 100644
index 00000000000..3139d9960fd
--- /dev/null
+++ b/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts
@@ -0,0 +1,54 @@
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+import type {
+  ElementSelectorController,
+  ElementSelectorState,
+} from '@src/core/element-selector/index.js';
+
+/**
+ * Bridges an {@link ElementSelectorController}'s `change` event to a Lit host's
+ * update cycle.
+ *
+ * The core is a plain emitter with no knowledge of Lit — that is what lets a Vue
+ * component bind to the same instance — so something has to translate "state
+ * changed" into `requestUpdate()`. A `ReactiveController` is the idiomatic place
+ * for it, and keeping it in the component folder rather than in `src/core/`
+ * is what keeps the core free of a Lit import.
+ */
+export class ElementSelectorHostController implements ReactiveController {
+  #off: (() => void) | null = null;
+
+  constructor(
+    private readonly host: ReactiveControllerHost,
+    private readonly source: () => ElementSelectorController | null
+  ) {
+    host.addController(this);
+  }
+
+  hostConnected(): void {
+    this.#subscribe();
+  }
+
+  hostDisconnected(): void {
+    this.#unsubscribe();
+  }
+
+  /** Call when the host's controller reference changes. */
+  resubscribe(): void {
+    this.#unsubscribe();
+    this.#subscribe();
+  }
+
+  get state(): ElementSelectorState | null {
+    return this.source()?.state ?? null;
+  }
+
+  #subscribe(): void {
+    this.#off =
+      this.source()?.on('change', () => this.host.requestUpdate()) ?? null;
+  }
+
+  #unsubscribe(): void {
+    this.#off?.();
+    this.#off = null;
+  }
+}
diff --git a/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.stories.ts b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.stories.ts
new file mode 100644
index 00000000000..76c04043108
--- /dev/null
+++ b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.stories.ts
@@ -0,0 +1,227 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+import {expect, userEvent, waitFor} from 'storybook/test';
+import {html} from 'lit';
+
+import './element-selector-modal.js';
+import type CraftElementSelectorModal from './element-selector-modal.js';
+import {ElementSelectorController} from '@src/core/element-selector/index.js';
+
+const MODAL_ID = 'storybook-element-selector-modal';
+
+interface ModalArgs {
+  label: string;
+  showTitle: boolean;
+  canSubmit: boolean;
+  busy: boolean;
+  loading: boolean;
+  nonModal: boolean;
+  fullscreen: boolean;
+  rows: number;
+}
+
+const modal = () =>
+  document.getElementById(MODAL_ID) as CraftElementSelectorModal;
+
+/** Stands in for the real element index, which is Vue and lives in the app. */
+function stubIndex(rows: number) {
+  return html`
+    <div
+      style="display:flex;height:100%;min-height:0;border-top:1px solid var(--c-border-subtle,#ddd)"
+    >
+      <nav
+        style="width:180px;flex:none;padding:12px;border-right:1px solid var(--c-border-subtle,#ddd);overflow:auto"
+      >
+        <div style="font-weight:600;margin-bottom:8px">Sources</div>
+        ${['All entries', 'News', 'Pages'].map(
+          (source) => html`<div style="padding:4px 0">${source}</div>`
+        )}
+      </nav>
+      <div style="flex:1;min-width:0;display:flex;flex-direction:column">
+        <div
+          style="flex:none;padding:12px;border-bottom:1px solid var(--c-border-subtle,#ddd)"
+        >
+          Toolbar
+        </div>
+        <div
+          style="flex:1;min-height:0;overflow:auto;padding:12px"
+          tabindex="0"
+          role="group"
+          aria-label="Results"
+        >
+          ${Array.from(
+            {length: rows},
+            (_, i) => html`<div style="padding:6px 0">Element ${i + 1}</div>`
+          )}
+        </div>
+      </div>
+    </div>
+  `;
+}
+
+const meta = {
+  title: 'Components/ElementSelectorModal',
+  component: 'craft-element-selector-modal',
+  args: {
+    label: 'Choose an entry',
+    showTitle: true,
+    canSubmit: false,
+    busy: false,
+    loading: false,
+    nonModal: false,
+    fullscreen: false,
+    rows: 40,
+  },
+  parameters: {layout: 'centered'},
+  render(args: ModalArgs) {
+    return html`
+      <craft-element-selector-modal
+        id=${MODAL_ID}
+        label=${args.label}
+        ?show-title=${args.showTitle}
+        ?can-submit=${args.canSubmit}
+        ?busy=${args.busy}
+        ?loading=${args.loading}
+        ?non-modal=${args.nonModal}
+        ?fullscreen=${args.fullscreen}
+      >
+        ${stubIndex(args.rows)}
+      </craft-element-selector-modal>
+
+      <craft-button @click=${() => (modal().opened = true)}>
+        Open selector
+      </craft-button>
+    `;
+  },
+} satisfies Meta<ModalArgs>;
+
+export default meta;
+type Story = StoryObj<ModalArgs>;
+
+export const Default: Story = {};
+
+export const WithSelection: Story = {
+  args: {canSubmit: true},
+};
+
+/** Mid-save: both buttons are out, and the index is inert rather than merely dim. */
+export const Busy: Story = {
+  args: {canSubmit: true, busy: true},
+};
+
+export const Loading: Story = {
+  args: {loading: true, rows: 0},
+};
+
+export const HiddenTitle: Story = {
+  args: {showTitle: false},
+};
+
+export const Fullscreen: Story = {
+  args: {fullscreen: true},
+};
+
+/**
+ * Out of the top layer, so `<body>`-appended menus — most of the legacy jQuery
+ * CP — still paint above it. Used by the asset-move folder picker.
+ */
+export const NonModal: Story = {
+  args: {nonModal: true},
+};
+
+/**
+ * The real thing: bound to a controller, which owns open state, the labels and
+ * whether Select is available.
+ */
+export const BoundToAController: Story = {
+  render(args: ModalArgs) {
+    const controller = new ElementSelectorController({
+      elementType: 'CraftCms\\Cms\\Entry\\Elements\\Entry',
+      modalTitle: args.label,
+      showTitle: true,
+      hideOnSelect: false,
+      loadIndexBody: async () => ({html: '', props: {}}),
+      // Stands in for the opener's async work, so `busy` is observable.
+      onSelect: () => new Promise<void>((resolve) => setTimeout(resolve, 1200)),
+    });
+
+    const select = () =>
+      controller.setSelection([
+        {
+          id: 1,
+          siteId: 1,
+          label: 'Element 1',
+          status: 'live',
+          url: null,
+          hasThumb: false,
+        },
+      ]);
+
+    return html`
+      <craft-element-selector-modal id=${MODAL_ID} .controller=${controller}>
+        ${stubIndex(args.rows)}
+        <craft-button
+          slot="secondary-actions"
+          data-testid="simulate-selection"
+          @click=${select}
+        >
+          Simulate a selection
+        </craft-button>
+      </craft-element-selector-modal>
+
+      <craft-button data-testid="open" @click=${() => controller.open()}>
+        Open selector
+      </craft-button>
+    `;
+  },
+  async play({canvasElement}) {
+    // Query by test id, not by tag: the first craft-button in the DOM is the
+    // one slotted inside the modal, not the opener.
+    await userEvent.click(
+      canvasElement.querySelector('[data-testid="open"]') as HTMLElement
+    );
+
+    const element = canvasElement.querySelector(
+      'craft-element-selector-modal'
+    ) as CraftElementSelectorModal;
+
+    await waitFor(() => expect(element.opened).toBe(true));
+
+    // `showModal()` puts it in the top layer; `:modal` is the observable proof,
+    // and it is the reason the non-modal escape hatch exists for legacy content.
+    const dialog = element.shadowRoot!.querySelector('dialog')!;
+    await expect(dialog.matches(':modal')).toBe(true);
+
+    // Select is unavailable until the controller reports a selection.
+    const selectButton = element.shadowRoot!.querySelector(
+      '[part="select"]'
+    ) as HTMLElement;
+    await expect(selectButton.hasAttribute('disabled')).toBe(true);
+
+    await userEvent.click(
+      element.querySelector('[data-testid="simulate-selection"]') as HTMLElement
+    );
+    await waitFor(() =>
+      expect(selectButton.hasAttribute('disabled')).toBe(false)
+    );
+
+    // Real hit-testing, not just a dispatched click: Lion's LionButton base
+    // paints an absolutely-positioned :host::before 44px click target, which has
+    // previously swallowed pointer events aimed at content inside a shadow root.
+    // elementFromPoint is what catches that; element.click() would not.
+    const box = selectButton.getBoundingClientRect();
+    const hit = element.shadowRoot!.elementFromPoint(
+      box.left + box.width / 2,
+      box.top + box.height / 2
+    );
+    await expect(selectButton.contains(hit) || selectButton === hit).toBe(true);
+
+    // Submitting holds `busy`, which makes the index inert.
+    await userEvent.click(selectButton);
+    await waitFor(() => expect(element.busy).toBe(true));
+    await expect(
+      element.shadowRoot!.querySelector('.body')!.hasAttribute('inert')
+    ).toBe(true);
+
+    await waitFor(() => expect(element.busy).toBe(false), {timeout: 3000});
+  },
+};
diff --git a/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.styles.ts b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.styles.ts
new file mode 100644
index 00000000000..d1b5f0287d1
--- /dev/null
+++ b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.styles.ts
@@ -0,0 +1,98 @@
+import {css} from 'lit';
+
+export default css`
+  :host {
+    /*
+      An element index needs room: a near-fullscreen surface rather than the
+      confirmation-sized default craft-dialog ships with.
+    */
+    --_dialog-inline-size: var(--c-dialog-inline-size, min(96vw, 80rem));
+    --_dialog-min-inline-size: var(
+      --c-dialog-min-inline-size,
+      min(96vw, 20rem)
+    );
+    --_dialog-max-inline-size: var(--c-dialog-max-inline-size, 96vw);
+    --_dialog-max-block-size: var(--c-dialog-max-block-size, 90dvh);
+
+    /*
+      The index has its own internal scrolling regions (a sticky toolbar over a
+      scrolling result list), so it needs a resolved height to fill rather than
+      a body that grows to fit it.
+    */
+    --_dialog-block-size: var(--c-dialog-block-size, 90dvh);
+  }
+
+  .surface {
+    block-size: var(--_dialog-block-size);
+  }
+
+  :host([fullscreen]) {
+    --_dialog-block-size: var(--c-dialog-block-size, 100dvh);
+  }
+
+  /* The index supplies its own padding, and its sidebar runs edge to edge. */
+  .body {
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+
+  .loading {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 1;
+    min-block-size: 0;
+  }
+
+  .header {
+    padding-block-end: 0;
+  }
+
+  /*
+    Kept in the accessibility tree when the title is hidden: the <dialog> is
+    labelled by it, so removing it would leave the dialog unnamed.
+  */
+  .title--hidden {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  :host([show-title]) .header {
+    padding-block-end: var(--c-spacing-md);
+  }
+
+  .footer {
+    /* Secondary actions left, primary right — as the legacy footer did. */
+    justify-content: space-between;
+    align-items: center;
+    gap: var(--c-spacing-md);
+    padding-block-start: var(--c-spacing-md);
+    border-block-start: 1px solid var(--c-border-subtle, transparent);
+  }
+
+  .footer__group {
+    display: flex;
+    align-items: center;
+    gap: var(--c-spacing-sm);
+  }
+
+  /*
+    While a selection is being saved, the index and the secondary actions stop
+    responding. The interaction block itself is the inert attribute set in
+    renderBody/renderFooter, which reaches slotted content this component does
+    not own; these rules only supply the matching visual state.
+  */
+  :host([busy]) .body,
+  :host([busy]) .footer__group--secondary {
+    opacity: 0.6;
+  }
+`;
diff --git a/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.test.ts b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.test.ts
new file mode 100644
index 00000000000..9fb0e951be9
--- /dev/null
+++ b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.test.ts
@@ -0,0 +1,348 @@
+import {beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+import type CraftElementSelectorModal from './element-selector-modal.js';
+import './element-selector-modal.js';
+import type {
+  ElementSelectorController,
+  ElementSelectorState,
+} from '@src/core/element-selector/index.js';
+
+if (typeof HTMLDialogElement !== 'undefined') {
+  HTMLDialogElement.prototype.showModal ??= function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.show ??= function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.close ??= function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  };
+}
+
+async function createModal(
+  configure: (modal: CraftElementSelectorModal) => void = () => {}
+): Promise<CraftElementSelectorModal> {
+  const modal = document.createElement(
+    'craft-element-selector-modal'
+  ) as CraftElementSelectorModal;
+  const index = document.createElement('div');
+  index.className = 'stub-index';
+  index.textContent = 'Index';
+  modal.append(index);
+  configure(modal);
+  document.body.append(modal);
+  await modal.updateComplete;
+  return modal;
+}
+
+function shadow<E extends Element = HTMLElement>(
+  modal: CraftElementSelectorModal,
+  selector: string
+): E | null {
+  return modal.shadowRoot!.querySelector<E>(selector);
+}
+
+const button = (modal: CraftElementSelectorModal, part: 'cancel' | 'select') =>
+  shadow<HTMLElement>(modal, `[part="${part}"]`)!;
+
+function state(
+  overrides: Partial<ElementSelectorState> = {}
+): ElementSelectorState {
+  return {
+    open: true,
+    loading: false,
+    busy: false,
+    selection: [],
+    disabledElementIds: [],
+    indexBody: {html: '', props: {}},
+    error: null,
+    title: 'Choose an entry',
+    showTitle: true,
+    selectLabel: 'Select',
+    canSubmit: false,
+    canCancel: true,
+    ...overrides,
+  };
+}
+
+/**
+ * A hand-rolled stand-in rather than a real controller: this file is about the
+ * chrome, and the controller has its own suite on the node environment.
+ */
+function fakeController(initial = state()) {
+  const listeners = new Set<(s: ElementSelectorState) => void>();
+  let current = initial;
+
+  return {
+    submit: vi.fn(),
+    cancel: vi.fn(),
+    get state() {
+      return current;
+    },
+    on(_event: string, listener: (s: ElementSelectorState) => void) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    push(next: Partial<ElementSelectorState>) {
+      current = {...current, ...next};
+      listeners.forEach((listener) => listener(current));
+    },
+  };
+}
+
+const bind = (
+  modal: CraftElementSelectorModal,
+  controller: ReturnType<typeof fakeController>
+) => {
+  modal.controller = controller as unknown as ElementSelectorController;
+};
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('chrome', () => {
+  it('renders a heading, a body slot and a footer', async () => {
+    const modal = await createModal((m) => {
+      m.label = 'Choose';
+      m.showTitle = true;
+    });
+
+    expect(shadow(modal, '[part="title"]')!.textContent!.trim()).toBe('Choose');
+    expect(shadow(modal, '.body slot')).not.toBeNull();
+    expect(shadow(modal, '[part="footer"]')).not.toBeNull();
+  });
+
+  it('keeps the heading in the a11y tree when the title is hidden', async () => {
+    // The dialog is labelled by it, so it must not be removed — only hidden.
+    const modal = await createModal((m) => {
+      m.label = 'Choose';
+    });
+    const title = shadow(modal, '[part="title"]')!;
+
+    expect(modal.showTitle).toBe(false);
+    expect(title.classList.contains('title--hidden')).toBe(true);
+    expect(shadow(modal, 'dialog')!.getAttribute('aria-labelledby')).toBe(
+      title.id
+    );
+  });
+
+  it('projects the index without relocating it', async () => {
+    const modal = await createModal();
+    const index = modal.querySelector('.stub-index')!;
+    const slot = shadow<HTMLSlotElement>(modal, '.body slot')!;
+
+    expect(index.parentElement).toBe(modal);
+    expect(slot.assignedNodes({flatten: true})).toContain(index);
+  });
+
+  it('exposes the footer slots', async () => {
+    const modal = await createModal();
+
+    expect(shadow(modal, 'slot[name="secondary-actions"]')).not.toBeNull();
+    expect(shadow(modal, 'slot[name="primary-actions"]')).not.toBeNull();
+  });
+
+  it('shows a spinner while loading with no index yet', async () => {
+    const modal = await createModal((m) => {
+      m.loading = true;
+    });
+
+    expect(shadow(modal, '.loading craft-spinner')).not.toBeNull();
+  });
+});
+
+describe('unbound (attribute-driven)', () => {
+  it('disables Select until can-submit is set', async () => {
+    const modal = await createModal();
+    expect(button(modal, 'select').hasAttribute('disabled')).toBe(true);
+
+    modal.canSubmit = true;
+    await modal.updateComplete;
+
+    expect(button(modal, 'select').hasAttribute('disabled')).toBe(false);
+  });
+
+  it('uses the given labels, falling back to defaults', async () => {
+    const modal = await createModal();
+    expect(button(modal, 'select').textContent!.trim()).toBeTruthy();
+
+    modal.selectLabel = 'Choose it';
+    modal.cancelLabel = 'Never mind';
+    await modal.updateComplete;
+
+    expect(button(modal, 'select').textContent!.trim()).toBe('Choose it');
+    expect(button(modal, 'cancel').textContent!.trim()).toBe('Never mind');
+  });
+
+  it('emits craft-select when Select is clicked', async () => {
+    const modal = await createModal((m) => {
+      m.canSubmit = true;
+    });
+    const seen = vi.fn();
+    modal.addEventListener('craft-select', seen);
+
+    button(modal, 'select').click();
+
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores a Select click while it cannot submit', async () => {
+    const modal = await createModal();
+    const seen = vi.fn();
+    modal.addEventListener('craft-select', seen);
+
+    button(modal, 'select').click();
+
+    expect(seen).not.toHaveBeenCalled();
+  });
+
+  it('emits craft-cancel and closes when Cancel is clicked', async () => {
+    const modal = await createModal((m) => m.setAttribute('open', ''));
+    const seen = vi.fn();
+    modal.addEventListener('craft-cancel', seen);
+
+    button(modal, 'cancel').click();
+    await modal.updateComplete;
+
+    expect(seen).toHaveBeenCalledTimes(1);
+    expect(modal.opened).toBe(false);
+  });
+});
+
+describe('busy', () => {
+  it('disables both buttons and marks the index inert', async () => {
+    const modal = await createModal((m) => {
+      m.canSubmit = true;
+      m.busy = true;
+    });
+
+    expect(button(modal, 'cancel').hasAttribute('disabled')).toBe(true);
+    expect(button(modal, 'select').hasAttribute('loading')).toBe(true);
+    expect(shadow(modal, '.body')!.hasAttribute('inert')).toBe(true);
+    expect(
+      shadow(modal, '.footer__group--secondary')!.hasAttribute('inert')
+    ).toBe(true);
+  });
+
+  it('reflects busy to an attribute for styling', async () => {
+    const modal = await createModal((m) => {
+      m.busy = true;
+    });
+
+    expect(modal.hasAttribute('busy')).toBe(true);
+  });
+
+  it('refuses a Cancel click', async () => {
+    const modal = await createModal((m) => {
+      m.setAttribute('open', '');
+      m.busy = true;
+    });
+    const seen = vi.fn();
+    modal.addEventListener('craft-cancel', seen);
+
+    button(modal, 'cancel').click();
+    await modal.updateComplete;
+
+    expect(seen).not.toHaveBeenCalled();
+    expect(modal.opened).toBe(true);
+  });
+});
+
+describe('bound to a controller', () => {
+  it('takes its state from the controller', async () => {
+    const controller = fakeController();
+    const modal = await createModal((m) => bind(m, controller));
+    await modal.updateComplete;
+
+    expect(modal.opened).toBe(true);
+    expect(modal.label).toBe('Choose an entry');
+    expect(modal.showTitle).toBe(true);
+    expect(button(modal, 'select').hasAttribute('disabled')).toBe(true);
+  });
+
+  it('re-renders when the controller emits change', async () => {
+    const controller = fakeController();
+    const modal = await createModal((m) => bind(m, controller));
+    await modal.updateComplete;
+
+    controller.push({canSubmit: true, selectLabel: 'Add'});
+    await modal.updateComplete;
+
+    expect(modal.canSubmit).toBe(true);
+    expect(button(modal, 'select').textContent!.trim()).toBe('Add');
+  });
+
+  it('lets the controller win over locally-set properties', async () => {
+    // One direction only: state flows out of the controller, never into it.
+    const controller = fakeController();
+    const modal = await createModal((m) => bind(m, controller));
+
+    modal.canSubmit = true;
+    await modal.updateComplete;
+
+    expect(modal.canSubmit).toBe(false);
+  });
+
+  it('routes Select to the controller', async () => {
+    const controller = fakeController(state({canSubmit: true}));
+    const modal = await createModal((m) => bind(m, controller));
+    await modal.updateComplete;
+
+    button(modal, 'select').click();
+
+    expect(controller.submit).toHaveBeenCalledTimes(1);
+  });
+
+  it('routes Cancel to the controller rather than closing itself', async () => {
+    const controller = fakeController();
+    const modal = await createModal((m) => bind(m, controller));
+    await modal.updateComplete;
+
+    button(modal, 'cancel').click();
+    await modal.updateComplete;
+
+    expect(controller.cancel).toHaveBeenCalledTimes(1);
+    // The controller still reports open, so the modal stays open — that is what
+    // lets it refuse a dismissal mid-save.
+    expect(modal.opened).toBe(true);
+  });
+
+  it('closes when the controller says it has closed', async () => {
+    const controller = fakeController();
+    const modal = await createModal((m) => bind(m, controller));
+    await modal.updateComplete;
+
+    controller.push({open: false});
+    await modal.updateComplete;
+
+    expect(modal.opened).toBe(false);
+  });
+
+  it('unsubscribes from the previous controller when rebound', async () => {
+    const first = fakeController();
+    const second = fakeController(state({title: 'Second'}));
+    const modal = await createModal((m) => bind(m, first));
+    await modal.updateComplete;
+
+    bind(modal, second);
+    await modal.updateComplete;
+    expect(modal.label).toBe('Second');
+
+    first.push({title: 'Stale'});
+    await modal.updateComplete;
+
+    expect(modal.label).toBe('Second');
+  });
+
+  it('stops listening once disconnected', async () => {
+    const controller = fakeController();
+    const modal = await createModal((m) => bind(m, controller));
+    await modal.updateComplete;
+
+    modal.remove();
+    controller.push({title: 'After removal'});
+    await modal.updateComplete;
+
+    expect(modal.label).toBe('Choose an entry');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts
new file mode 100644
index 00000000000..9be0d202bbd
--- /dev/null
+++ b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts
@@ -0,0 +1,254 @@
+import type {PropertyValues, TemplateResult} from 'lit';
+import {html, nothing} from 'lit';
+import {property, state} from 'lit/decorators.js';
+import {t} from '@src/utilities/translate.js';
+import type {ElementSelectorController} from '@src/core/element-selector/index.js';
+import CraftDialog from '../dialog/dialog.js';
+import {ElementSelectorHostController} from './controller-host.js';
+import styles from './element-selector-modal.styles.js';
+import '../button/button.js';
+import '../spinner/spinner.js';
+
+/** Below this the index hides its sidebar behind a toggle. */
+const NARROW_THRESHOLD = 550;
+
+/**
+ * craft-element-selector-modal is the chrome around an element index.
+ *
+ * It renders the dialog, the heading and the footer, and nothing else — the
+ * index itself is slotted in, because the index is Vue in this app and a legacy
+ * jQuery widget in the asset-move flow, and neither belongs in a Lit component.
+ *
+ * Bind it to an {@link ElementSelectorController} through the `controller`
+ * property and it becomes a view of that controller: state flows out of the
+ * controller into this component's reflected properties, and user intent flows
+ * back in through `submit()` and `cancel()`. Nothing passes between this
+ * component and the slotted index — they only ever talk to the controller, which
+ * is what stops a web component and a Vue component from drifting apart.
+ *
+ * Without a controller it falls back to its own attributes, so it can be driven
+ * declaratively in Storybook or by a consumer that only wants the chrome.
+ *
+ * @slot - The element index.
+ * @slot secondary-actions - Footer content pinned left.
+ * @slot primary-actions - Footer buttons placed before Cancel and Select.
+ * @csspart footer - The footer row.
+ * @csspart secondary-actions - The left-hand footer group.
+ * @csspart primary-actions - The right-hand footer group.
+ * @csspart cancel - The Cancel button.
+ * @csspart select - The Select button.
+ *
+ * @fires craft-select - The user asked to accept the selection.
+ * @fires craft-cancel - The user asked to dismiss the modal.
+ *
+ * @example
+ * const modal = document.createElement('craft-element-selector-modal');
+ * modal.controller = new ElementSelectorController({elementType, onSelect});
+ * modal.append(index);
+ * document.body.append(modal);
+ * await modal.controller.open();
+ */
+export default class CraftElementSelectorModal extends CraftDialog {
+  static override styles = [...(CraftDialog.styles as []), styles];
+
+  /**
+   * The business layer. Set as a property, never constructed here — one
+   * controller may be shared with a Vue view of the same modal.
+   */
+  @property({attribute: false}) controller: ElementSelectorController | null =
+    null;
+
+  /** Show the heading. When false it stays in the a11y tree but is hidden. */
+  @property({type: Boolean, attribute: 'show-title', reflect: true})
+  showTitle = false;
+
+  @property({attribute: 'select-label'}) selectLabel = '';
+
+  @property({attribute: 'cancel-label'}) cancelLabel = '';
+
+  /** A submit is in flight. */
+  @property({type: Boolean, reflect: true}) busy = false;
+
+  /** The index body is being fetched. */
+  @property({type: Boolean, reflect: true}) loading = false;
+
+  @property({type: Boolean, attribute: 'can-submit', reflect: true})
+  canSubmit = false;
+
+  /**
+   * Reflected from the surface's width. The slotted index keys its sidebar
+   * toggle off it — the component itself does not act on it.
+   */
+  @property({type: Boolean, reflect: true}) narrow = false;
+
+  @state() private hasIndex = false;
+
+  #binding = new ElementSelectorHostController(this, () => this.controller);
+
+  #resizeObserver: ResizeObserver | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObserver = new ResizeObserver(([entry]) => {
+        if (entry) {
+          this.narrow = entry.contentRect.width < NARROW_THRESHOLD;
+        }
+      });
+    }
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.#resizeObserver?.disconnect();
+  }
+
+  protected override willUpdate(changed: PropertyValues): void {
+    if (changed.has('controller')) {
+      this.#binding.resubscribe();
+    }
+
+    // One direction only: when bound, the controller is the source of truth for
+    // every one of these, and the properties are a reflection of it rather than
+    // an input to it.
+    const state = this.#binding.state;
+
+    if (state) {
+      this.opened = state.open;
+      this.busy = state.busy;
+      this.loading = state.loading;
+      this.canSubmit = state.canSubmit;
+      this.label = state.title;
+      this.showTitle = state.showTitle;
+      this.selectLabel = state.selectLabel;
+      this.hasIndex = state.indexBody !== null;
+    }
+
+    super.willUpdate(changed);
+  }
+
+  protected override firstUpdated(changed: PropertyValues): void {
+    super.firstUpdated(changed);
+
+    const surface = this.shadowRoot?.querySelector('.surface');
+
+    if (surface) {
+      this.#resizeObserver?.observe(surface);
+    }
+  }
+
+  /** Heading only — dismissal lives in the footer's Cancel button. */
+  protected override renderHeader(): TemplateResult {
+    return html`
+      <header class="header" part="header">
+        <h1
+          class=${this.showTitle ? 'title' : 'title title--hidden'}
+          part="title"
+          id=${this.titleId}
+        >
+          ${this.label}
+        </h1>
+      </header>
+    `;
+  }
+
+  protected override renderBody(): TemplateResult {
+    return html`
+      <div class="body" part="body" ?inert=${this.busy}>
+        ${this.loading && !this.hasIndex
+          ? html`<div class="loading"><craft-spinner></craft-spinner></div>`
+          : nothing}
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  protected override renderFooter(): TemplateResult {
+    return html`
+      <footer class="footer" part="footer">
+        <div
+          class="footer__group footer__group--secondary"
+          part="secondary-actions"
+          ?inert=${this.busy}
+        >
+          <slot name="secondary-actions"></slot>
+        </div>
+        <div class="footer__group" part="primary-actions">
+          <slot name="primary-actions"></slot>
+          <craft-button
+            part="cancel"
+            type="button"
+            variant="fill"
+            ?disabled=${this.busy}
+            @click=${this.#onCancelClick}
+          >
+            ${this.cancelLabel || t('Cancel')}
+          </craft-button>
+          <craft-button
+            part="select"
+            type="button"
+            variant="primary"
+            ?disabled=${!this.canSubmit}
+            ?loading=${this.busy}
+            @click=${this.#onSelectClick}
+          >
+            ${this.selectLabel || t('Select')}
+          </craft-button>
+        </div>
+      </footer>
+    `;
+  }
+
+  /** Accept the current selection. */
+  submit(): void {
+    if (!this.canSubmit) {
+      return;
+    }
+
+    this.dispatchEvent(
+      new CustomEvent('craft-select', {bubbles: true, composed: true})
+    );
+
+    // The event is a notification for onlookers, not the mechanism — routing the
+    // action through it as well would give one intent two paths.
+    void this.controller?.submit();
+  }
+
+  /**
+   * Every dismissal — Cancel, Escape, the backdrop — arrives here through
+   * `CraftDialog`. When bound, the controller decides: it refuses while busy,
+   * which is what keeps the modal up mid-save.
+   */
+  protected override requestClose(): void {
+    this.dispatchEvent(
+      new CustomEvent('craft-cancel', {bubbles: true, composed: true})
+    );
+
+    if (this.controller) {
+      this.controller.cancel();
+      return;
+    }
+
+    super.requestClose();
+  }
+
+  #onSelectClick = (): void => {
+    this.submit();
+  };
+
+  #onCancelClick = (): void => {
+    if (this.busy) {
+      return;
+    }
+
+    this.requestClose();
+  };
+}
+
+if (!customElements.get('craft-element-selector-modal')) {
+  customElements.define(
+    'craft-element-selector-modal',
+    CraftElementSelectorModal
+  );
+}
diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index d900fe693cf..637a069e3b9 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -26,6 +26,8 @@ export {default as CraftCombobox} from './components/combobox/combobox.js';
 export {default as CraftCopyAttribute} from './components/copy-attribute/copy-attribute.js';
 export {default as CraftCopyButton} from './components/copy-button/copy-button.js';
 export {default as CraftDialog} from './components/dialog/dialog.js';
+export {default as CraftElementSelectorModal} from './components/element-selector-modal/element-selector-modal.js';
+export {ElementSelectorHostController} from './components/element-selector-modal/controller-host.js';
 export {default as CraftDisclosure} from './components/disclosure/disclosure.js';
 export {default as CraftEmpty} from './components/empty/empty.js';
 export {default as CraftField} from './components/field/field.js';

From 1b1616fc48fe3a112601f49534b053d30c12e8c1 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 21 Aug 2026 17:36:44 -0500
Subject: [PATCH 17/24] Render the element selector modal from Vue on the new
 core

---
 .../ElementSelectorModal.test.ts              | 207 ++++++++++++++++++
 .../ElementSelectorModal.vue                  |  54 +++++
 .../ModalElementIndex.vue                     |   5 +-
 .../create-element-selector-modal.ts          | 142 ++++++++++++
 .../useElementSelectorController.test.ts      | 133 +++++++++++
 .../useElementSelectorController.ts           |  60 +++++
 .../useModalElementIndex.ts                   |  56 +++--
 .../js/modules/link-field/craft-link-field.ts |  24 +-
 .../markdown-field/behaviors/assets.ts        |  76 +++----
 src/Http/ViewModels/ModalIndexViewModel.php   |  25 +++
 10 files changed, 714 insertions(+), 68 deletions(-)
 create mode 100644 resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts
 create mode 100644 resources/js/modules/element-selector-modal/ElementSelectorModal.vue
 create mode 100644 resources/js/modules/element-selector-modal/create-element-selector-modal.ts
 create mode 100644 resources/js/modules/element-selector-modal/useElementSelectorController.test.ts
 create mode 100644 resources/js/modules/element-selector-modal/useElementSelectorController.ts

diff --git a/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts b/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts
new file mode 100644
index 00000000000..10a784c169c
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts
@@ -0,0 +1,207 @@
+import {createApp, defineComponent, h, nextTick} from 'vue';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+import {ElementSelectorController, type ElementInfo} from '@craftcms/ui';
+
+/**
+ * The real index pulls the whole element-index component tree and its
+ * composables; this stub stands in for it so the test is about the wiring —
+ * controller to chrome, index to controller — and nothing else.
+ *
+ * It keeps the real component's contract: emits `selection-change` / `choose`,
+ * exposes `clearSelection`, takes `disabled-element-ids`.
+ */
+const stub = vi.hoisted(() => ({
+  clearSelection: vi.fn(),
+  lastProps: null as Record<string, any> | null,
+  emit: null as ((event: string, payload?: unknown) => void) | null,
+}));
+
+vi.mock('./ModalElementIndex.vue', async () => {
+  const {defineComponent: define, h: create} = await import('vue');
+
+  return {
+    default: define({
+      name: 'ModalElementIndexStub',
+      props: ['action', 'initial', 'params', 'disabledElementIds'],
+      emits: ['selection-change', 'choose'],
+      setup(props, {emit, expose}) {
+        stub.lastProps = props as Record<string, any>;
+        stub.emit = emit as (event: string, payload?: unknown) => void;
+        expose({clearSelection: stub.clearSelection});
+        return () => create('div', {class: 'index-stub'});
+      },
+    }),
+  };
+});
+
+function element(id: number): ElementInfo {
+  return {
+    id,
+    siteId: 1,
+    label: `Element ${id}`,
+    status: null,
+    url: null,
+    hasThumb: false,
+  };
+}
+
+function controller(options = {}) {
+  return new ElementSelectorController({
+    elementType: 'CraftCms\\Cms\\Entry\\Elements\\Entry',
+    modalTitle: 'Choose an entry',
+    hideOnSelect: false,
+    loadIndexBody: async () => ({html: '', props: {total: 2}}),
+    ...options,
+  });
+}
+
+async function mountModal(instance: ElementSelectorController) {
+  const {default: ElementSelectorModal} =
+    await import('./ElementSelectorModal.vue');
+
+  const app = createApp(
+    defineComponent({
+      setup: () => () => h(ElementSelectorModal, {controller: instance}),
+    })
+  );
+  app.config.compilerOptions.isCustomElement = (tag: string) =>
+    tag.includes('-');
+
+  const host = document.createElement('div');
+  document.body.append(host);
+  app.mount(host);
+  await nextTick();
+
+  return {
+    host,
+    unmount: () => app.unmount(),
+    modal: () =>
+      host.querySelector('craft-element-selector-modal') as HTMLElement & {
+        controller: ElementSelectorController | null;
+      },
+  };
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  stub.clearSelection.mockClear();
+  stub.lastProps = null;
+  stub.emit = null;
+});
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('ElementSelectorModal', () => {
+  it('hands the controller to the web component as a property', async () => {
+    const instance = controller();
+    const {modal, unmount} = await mountModal(instance);
+
+    expect(modal().controller).toBe(instance);
+    unmount();
+  });
+
+  it('holds the index back until the body has loaded', async () => {
+    const instance = controller();
+    const {host, unmount} = await mountModal(instance);
+
+    expect(host.querySelector('.index-stub')).toBeNull();
+
+    await instance.open();
+    await nextTick();
+
+    expect(host.querySelector('.index-stub')).not.toBeNull();
+    unmount();
+  });
+
+  it('passes the action, payload and params to the index', async () => {
+    const instance = controller();
+    const {unmount} = await mountModal(instance);
+
+    await instance.open();
+    await nextTick();
+
+    expect(stub.lastProps!.action).toBe('element-selector-modals/body');
+    expect(stub.lastProps!.initial).toEqual({total: 2});
+    expect(stub.lastProps!.params).toMatchObject({
+      context: 'modal',
+      elementType: 'CraftCms\\Cms\\Entry\\Elements\\Entry',
+    });
+    unmount();
+  });
+
+  it('routes the index’s selection into the controller', async () => {
+    const instance = controller();
+    const {unmount} = await mountModal(instance);
+    await instance.open();
+    await nextTick();
+
+    stub.emit!('selection-change', [element(1)]);
+    await nextTick();
+
+    expect(instance.state.selection.map((e) => e.id)).toEqual([1]);
+    expect(instance.state.canSubmit).toBe(true);
+    unmount();
+  });
+
+  it('routes a double-click choose into a submit', async () => {
+    const onSelect = vi.fn();
+    const instance = controller({onSelect});
+    const {unmount} = await mountModal(instance);
+    await instance.open();
+    await nextTick();
+
+    stub.emit!('selection-change', [element(1)]);
+    await nextTick();
+    stub.emit!('choose');
+    await nextTick();
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it('republishes disabled ids to the index reactively', async () => {
+    // The bug this whole seam exists to fix: the old modal passed these once by
+    // value and the index never saw an update.
+    const instance = controller({disabledElementIds: [1]});
+    const {unmount} = await mountModal(instance);
+    await instance.open();
+    await nextTick();
+
+    expect(stub.lastProps!.disabledElementIds).toEqual([1]);
+
+    instance.setDisabledElementIds([2, 3]);
+    await nextTick();
+
+    expect(stub.lastProps!.disabledElementIds).toEqual([2, 3]);
+    unmount();
+  });
+
+  it('registers the index so the controller can clear it', async () => {
+    const instance = controller({disableElementsOnSelect: true});
+    const {unmount} = await mountModal(instance);
+    await instance.open();
+    await nextTick();
+
+    stub.emit!('selection-change', [element(1)]);
+    await nextTick();
+    await instance.submit();
+
+    expect(stub.clearSelection).toHaveBeenCalled();
+    expect(instance.state.disabledElementIds).toEqual([1]);
+    unmount();
+  });
+
+  it('detaches the index on unmount', async () => {
+    const instance = controller();
+    const {unmount} = await mountModal(instance);
+    await instance.open();
+    await nextTick();
+    expect(instance.index).not.toBeNull();
+
+    unmount();
+
+    expect(instance.index).toBeNull();
+  });
+});
diff --git a/resources/js/modules/element-selector-modal/ElementSelectorModal.vue b/resources/js/modules/element-selector-modal/ElementSelectorModal.vue
new file mode 100644
index 00000000000..f9b9d0d123d
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/ElementSelectorModal.vue
@@ -0,0 +1,54 @@
+<script setup lang="ts">
+  import {onMounted, onUnmounted, ref} from 'vue';
+  import type {ElementSelectorController} from '@craftcms/ui';
+  import '@craftcms/ui/components/element-selector-modal/element-selector-modal';
+  import ModalElementIndex from './ModalElementIndex.vue';
+  import type {SelectedElement} from './useModalElementIndex';
+  import {useElementSelectorController} from './useElementSelectorController';
+
+  const props = defineProps<{controller: ElementSelectorController}>();
+
+  /**
+   * No emits: the controller is the event bus.
+   *
+   * Anything that wants to know about a selection listens to the controller (or
+   * passes `onSelect`), which is also what the web component and the imperative
+   * openers do. Re-emitting here would give one event two sources.
+   */
+  const {indexBody, disabledElementIds} = useElementSelectorController(
+    props.controller
+  );
+
+  const index = ref<InstanceType<typeof ModalElementIndex> | null>(null);
+
+  onMounted(() => {
+    props.controller.attachIndex({
+      clearSelection: () => index.value?.clearSelection(),
+    });
+  });
+
+  onUnmounted(() => props.controller.detachIndex());
+</script>
+
+<template>
+  <craft-element-selector-modal :controller="controller">
+    <!--
+      The index talks to the controller, never to the chrome around it — it emits
+      what happened and the controller decides what that means. That is what lets
+      the same index sit inside the web component here and inside a plugin's own
+      presentation elsewhere.
+    -->
+    <ModalElementIndex
+      v-if="indexBody"
+      ref="index"
+      :action="controller.options.bodyAction"
+      :initial="indexBody.props as any"
+      :params="controller.indexParams()"
+      :disabled-element-ids="disabledElementIds"
+      @selection-change="
+        (elements: SelectedElement[]) => controller.setSelection(elements)
+      "
+      @choose="() => controller.submit()"
+    />
+  </craft-element-selector-modal>
+</template>
diff --git a/resources/js/modules/element-selector-modal/ModalElementIndex.vue b/resources/js/modules/element-selector-modal/ModalElementIndex.vue
index 8f758f3c691..211028e9840 100644
--- a/resources/js/modules/element-selector-modal/ModalElementIndex.vue
+++ b/resources/js/modules/element-selector-modal/ModalElementIndex.vue
@@ -15,7 +15,8 @@
   } from './useModalElementIndex';
 
   const props = defineProps<{
-    url: string;
+    /** Bare action path; `actionClient` expands it against the CP trigger. */
+    action: string;
     initial: ContentIndexData;
     params: Record<string, unknown>;
     disabledElementIds?: number[];
@@ -27,7 +28,7 @@
   }>();
 
   const index = useModalElementIndex({
-    url: props.url,
+    action: props.action,
     initial: props.initial,
     params: props.params,
     disabledElementIds: () => props.disabledElementIds ?? [],
diff --git a/resources/js/modules/element-selector-modal/create-element-selector-modal.ts b/resources/js/modules/element-selector-modal/create-element-selector-modal.ts
new file mode 100644
index 00000000000..7709d471e1a
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/create-element-selector-modal.ts
@@ -0,0 +1,142 @@
+import {
+  createElementSelectorController,
+  type ElementSelectorController,
+  type ElementSelectorEvent,
+  type ElementSelectorEventMap,
+  type ElementSelectorOptions,
+} from '@craftcms/ui';
+import type {App} from 'vue';
+
+/**
+ * Settings the presentation layer consumes, which the core neither needs nor
+ * should know about.
+ *
+ * They are DOM concerns, and openers pass them in the same blob as the business
+ * settings, so the factory splits the blob rather than widening the core's
+ * options with fields it would only carry around.
+ */
+export interface ElementSelectorModalPresentationOptions {
+  /** Where to put focus when the modal closes. */
+  triggerElement?: HTMLElement | (() => HTMLElement | null) | null;
+  /** Legacy Garnish setting, accepted and ignored. */
+  closeOtherModals?: boolean;
+}
+
+export type ElementSelectorModalSettings = Partial<ElementSelectorOptions> &
+  ElementSelectorModalPresentationOptions;
+
+export interface ElementSelectorModalHandle {
+  readonly controller: ElementSelectorController;
+  readonly element: HTMLElement;
+  show(): Promise<void>;
+  hide(): void;
+  destroy(): void;
+  on<E extends ElementSelectorEvent>(
+    event: E,
+    listener: (data: ElementSelectorEventMap[E]) => void
+  ): () => void;
+  setDisabledElementIds(ids: number[]): void;
+  setBusy(busy: boolean): void;
+}
+
+const PRESENTATION_KEYS = ['triggerElement', 'closeOtherModals'] as const;
+
+function splitSettings(settings: ElementSelectorModalSettings) {
+  const presentation: ElementSelectorModalPresentationOptions = {};
+  const core = {...settings} as Record<string, unknown>;
+
+  for (const key of PRESENTATION_KEYS) {
+    if (key in core) {
+      (presentation as Record<string, unknown>)[key] = core[key];
+      delete core[key];
+    }
+  }
+
+  return {core: core as Partial<ElementSelectorOptions>, presentation};
+}
+
+function resolveFocusTarget(
+  target: ElementSelectorModalPresentationOptions['triggerElement']
+): HTMLElement | null {
+  return (typeof target === 'function' ? target() : target) ?? null;
+}
+
+/**
+ * Opens an element selector modal and returns a handle on it.
+ *
+ * The controller comes from the registry, so an element type with its own
+ * controller (assets, for their transforms) gets it. Presentation is the Vue
+ * modal, mounted into a detached host — which is why this is async, and why the
+ * Vue and element-index modules are imported here rather than at module scope: a
+ * page with a relation field on it shouldn't pay for the index unless a modal is
+ * actually opened.
+ *
+ * @example
+ * const modal = await createElementSelectorModal(elementType, {
+ *   multiSelect: true,
+ *   onSelect: (elements) => …,
+ * });
+ */
+export async function createElementSelectorModal(
+  elementType: string,
+  settings: ElementSelectorModalSettings = {}
+): Promise<ElementSelectorModalHandle> {
+  const {core, presentation} = splitSettings(settings);
+  const controller = createElementSelectorController({
+    ...core,
+    elementType,
+  });
+
+  const [
+    {createApp},
+    {default: ElementSelectorModal},
+    {createCpComponentRegistry},
+  ] = await Promise.all([
+    import('vue'),
+    import('./ElementSelectorModal.vue'),
+    import('@/bootstrap/components'),
+  ]);
+
+  const host = document.createElement('div');
+  host.className = 'element-selector-modal-host';
+  document.body.append(host);
+
+  const app: App = createApp(ElementSelectorModal, {controller});
+  createCpComponentRegistry().install(app);
+  app.config.compilerOptions.isCustomElement = (tag: string) =>
+    tag.includes('-');
+  app.mount(host);
+
+  // Focus restoration is the opener's business — the relation field wants focus
+  // to land on whatever replaced the chip it just removed, not on the trigger.
+  controller.on('close', () => {
+    const target = resolveFocusTarget(presentation.triggerElement);
+    target?.focus();
+  });
+
+  let destroyed = false;
+
+  const handle: ElementSelectorModalHandle = {
+    controller,
+    element: host,
+    show: () => controller.open(),
+    hide: () => controller.close(),
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+
+      destroyed = true;
+      controller.destroy();
+      app.unmount();
+      host.remove();
+    },
+    on: (event, listener) => controller.on(event, listener),
+    setDisabledElementIds: (ids) => controller.setDisabledElementIds(ids),
+    setBusy: (busy) => controller.setBusy(busy),
+  };
+
+  await controller.open();
+
+  return handle;
+}
diff --git a/resources/js/modules/element-selector-modal/useElementSelectorController.test.ts b/resources/js/modules/element-selector-modal/useElementSelectorController.test.ts
new file mode 100644
index 00000000000..2725658ce9b
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/useElementSelectorController.test.ts
@@ -0,0 +1,133 @@
+import {createApp, defineComponent, h, nextTick} from 'vue';
+import {describe, expect, it, vi} from 'vite-plus/test';
+import {ElementSelectorController, type ElementInfo} from '@craftcms/ui';
+import {useElementSelectorController} from './useElementSelectorController';
+
+function element(id: number): ElementInfo {
+  return {
+    id,
+    siteId: 1,
+    label: `Element ${id}`,
+    status: null,
+    url: null,
+    hasThumb: false,
+  };
+}
+
+function controller(options = {}) {
+  return new ElementSelectorController({
+    elementType: 'CraftCms\\Cms\\Entry\\Elements\\Entry',
+    loadIndexBody: async () => ({html: '', props: {total: 1}}),
+    ...options,
+  });
+}
+
+/** Mounts the composable and hands back what it returned, plus a disposer. */
+function mountComposable(instance: ElementSelectorController) {
+  let api!: ReturnType<typeof useElementSelectorController>;
+
+  const app = createApp(
+    defineComponent({
+      setup() {
+        api = useElementSelectorController(instance);
+        return () => h('div');
+      },
+    })
+  );
+
+  const host = document.createElement('div');
+  document.body.append(host);
+  app.mount(host);
+
+  return {api, unmount: () => app.unmount()};
+}
+
+describe('useElementSelectorController', () => {
+  it('starts from the controller’s current state', () => {
+    const instance = controller({modalTitle: 'Choose'});
+    const {api, unmount} = mountComposable(instance);
+
+    expect(api.state.value.title).toBe('Choose');
+    expect(api.open.value).toBe(false);
+    unmount();
+  });
+
+  it('tracks changes as they are emitted', async () => {
+    const instance = controller();
+    const {api, unmount} = mountComposable(instance);
+
+    instance.setSelection([element(1)]);
+    await nextTick();
+
+    expect(api.canSubmit.value).toBe(true);
+    expect(api.selection.value.map((e) => e.id)).toEqual([1]);
+    unmount();
+  });
+
+  it('exposes the loaded index body', async () => {
+    const instance = controller();
+    const {api, unmount} = mountComposable(instance);
+
+    await instance.open();
+    await nextTick();
+
+    expect(api.open.value).toBe(true);
+    expect(api.indexBody.value?.props).toEqual({total: 1});
+    unmount();
+  });
+
+  it('re-reads disabled ids when the opener republishes them', async () => {
+    // The old modal copied this into the index once by value, so later updates
+    // never reached it.
+    const instance = controller({disabledElementIds: [1]});
+    const {api, unmount} = mountComposable(instance);
+
+    expect(api.disabledElementIds.value).toEqual([1]);
+
+    instance.setDisabledElementIds([2, 3]);
+    await nextTick();
+
+    expect(api.disabledElementIds.value).toEqual([2, 3]);
+    unmount();
+  });
+
+  it('does not wrap the controller’s objects in a reactive proxy', () => {
+    // A shallowRef of a frozen snapshot: the object a Vue template reads is the
+    // same one the web component reads.
+    const instance = controller();
+    const {api, unmount} = mountComposable(instance);
+
+    expect(api.state.value).toBe(instance.state);
+    unmount();
+  });
+
+  it('forwards submit and cancel', async () => {
+    const onSelect = vi.fn();
+    const onCancel = vi.fn();
+    const instance = controller({onSelect, onCancel, hideOnSelect: false});
+    const {api, unmount} = mountComposable(instance);
+
+    instance.setSelection([element(1)]);
+    await nextTick();
+    api.submit();
+    await nextTick();
+    expect(onSelect).toHaveBeenCalledTimes(1);
+
+    await instance.open();
+    api.cancel();
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it('unsubscribes on unmount', async () => {
+    const instance = controller();
+    const {api, unmount} = mountComposable(instance);
+    const before = api.state.value;
+
+    unmount();
+    instance.setSelection([element(1)]);
+    await nextTick();
+
+    expect(api.state.value).toBe(before);
+  });
+});
diff --git a/resources/js/modules/element-selector-modal/useElementSelectorController.ts b/resources/js/modules/element-selector-modal/useElementSelectorController.ts
new file mode 100644
index 00000000000..a71fd1d807c
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/useElementSelectorController.ts
@@ -0,0 +1,60 @@
+import {
+  computed,
+  onUnmounted,
+  shallowRef,
+  type ComputedRef,
+  type Ref,
+} from 'vue';
+import type {
+  ElementInfo,
+  ElementSelectorController,
+  ElementSelectorState,
+} from '@craftcms/ui';
+
+export interface UseElementSelectorController {
+  state: Ref<ElementSelectorState>;
+  open: ComputedRef<boolean>;
+  busy: ComputedRef<boolean>;
+  loading: ComputedRef<boolean>;
+  canSubmit: ComputedRef<boolean>;
+  indexBody: ComputedRef<ElementSelectorState['indexBody']>;
+  disabledElementIds: ComputedRef<number[]>;
+  selection: ComputedRef<readonly ElementInfo[]>;
+  submit: () => void;
+  cancel: () => void;
+}
+
+/**
+ * Mirrors an {@link ElementSelectorController}'s state into Vue reactivity.
+ *
+ * The core is a plain emitter with no Vue import — that is what lets the web
+ * component bind to the same instance — so the bridge lives here. Each `change`
+ * carries a fresh frozen snapshot, which is why a `shallowRef` is enough and
+ * deliberately preferable: nothing wraps the controller's own objects in a
+ * reactive proxy, so the value a Vue template reads is the same object the web
+ * component reads.
+ *
+ * Subscribes immediately rather than in `onMounted`, so a controller that is
+ * already open when the component is created renders correctly on first paint.
+ */
+export function useElementSelectorController(
+  controller: ElementSelectorController
+): UseElementSelectorController {
+  const state = shallowRef<ElementSelectorState>(controller.state);
+  const off = controller.on('change', (next) => (state.value = next));
+
+  onUnmounted(off);
+
+  return {
+    state,
+    open: computed(() => state.value.open),
+    busy: computed(() => state.value.busy),
+    loading: computed(() => state.value.loading),
+    canSubmit: computed(() => state.value.canSubmit),
+    indexBody: computed(() => state.value.indexBody),
+    disabledElementIds: computed(() => [...state.value.disabledElementIds]),
+    selection: computed(() => state.value.selection),
+    submit: () => void controller.submit(),
+    cancel: () => controller.cancel(),
+  };
+}
diff --git a/resources/js/modules/element-selector-modal/useModalElementIndex.ts b/resources/js/modules/element-selector-modal/useModalElementIndex.ts
index 68ce12b46f6..57bbfd97ae2 100644
--- a/resources/js/modules/element-selector-modal/useModalElementIndex.ts
+++ b/resources/js/modules/element-selector-modal/useModalElementIndex.ts
@@ -1,4 +1,4 @@
-import {actionClient} from '@craftcms/ui';
+import {actionClient, type ElementInfo} from '@craftcms/ui';
 import {getCoreRowModel, useVueTable} from '@tanstack/vue-table';
 import type {RowSelectionState} from '@tanstack/table-core';
 import {computed, ref, watch} from 'vue';
@@ -16,19 +16,48 @@ import {createModalIndexVisitor} from './modal-index-visitor';
 
 type Row = Record<string, any>;
 
-/** What the modal hands back for each selected row. */
-export interface SelectedElement {
-  id: number;
-  siteId: number | null;
-  label: string;
-  status: string | null;
-  url: string | null;
-  hasThumb: boolean;
+/**
+ * What the modal hands back for each selected row.
+ *
+ * An alias of the core's `ElementInfo` rather than a second declaration of the
+ * same shape — the controller, the web component and this composable all have to
+ * agree on it, and two copies would drift.
+ */
+export type SelectedElement = ElementInfo;
+
+/**
+ * Row keys carried through to the selection payload.
+ *
+ * Not a blind spread of the row: a row is mostly rendered column HTML keyed by
+ * attribute, and forwarding that would put kilobytes of markup into every
+ * `onSelect` payload. These are the keys `ModalIndexViewModel::extraRowData()`
+ * adds on purpose — `kind`/`alt` for the Markdown field, the folder keys for the
+ * asset-move picker.
+ */
+const EXTRA_ROW_KEYS = [
+  'kind',
+  'alt',
+  'isFolder',
+  'folderId',
+  'folderUrl',
+  'canMoveTo',
+] as const;
+
+function extraRowData(row: Row): Record<string, unknown> {
+  const extras: Record<string, unknown> = {};
+
+  for (const key of EXTRA_ROW_KEYS) {
+    if (row[key] !== undefined) {
+      extras[key] = row[key];
+    }
+  }
+
+  return extras;
 }
 
 interface Options {
-  /** The `element-selector-modals/body` endpoint. */
-  url: string;
+  /** The `element-selector-modals/body` action path. */
+  action: string;
   /** The payload the modal opened with, so the first render needs no request. */
   initial: ContentIndexData;
   /** Params identifying the index — element type, sources, criteria, condition. */
@@ -58,7 +87,7 @@ export function useModalElementIndex(options: Options) {
     loading.value = true;
 
     try {
-      const {data} = await actionClient.post(options.url, {
+      const {data} = await actionClient.post(options.action, {
         ...options.params,
         ...query,
       });
@@ -72,7 +101,7 @@ export function useModalElementIndex(options: Options) {
   const visitor = createModalIndexVisitor(load);
   // The composables still want a route, but nothing navigates to it — every
   // request goes through the visitor above.
-  const route = {url: () => options.url};
+  const route = {url: () => options.action};
 
   const elementIndex = useContentIndexData(undefined, payload);
   const viewState = useElementIndexViewState(elementIndex);
@@ -166,6 +195,7 @@ export function useModalElementIndex(options: Options) {
    */
   const selectedElements = computed<SelectedElement[]>(() =>
     table.getSelectedRowModel().rows.map(({original}) => ({
+      ...extraRowData(original),
       id: Number(original.id),
       siteId: original.siteId != null ? Number(original.siteId) : null,
       label: String(original.label ?? original.title ?? original.id),
diff --git a/resources/js/modules/link-field/craft-link-field.ts b/resources/js/modules/link-field/craft-link-field.ts
index a4a1cd4d173..8130e899885 100644
--- a/resources/js/modules/link-field/craft-link-field.ts
+++ b/resources/js/modules/link-field/craft-link-field.ts
@@ -1,5 +1,5 @@
-import {t} from '@craftcms/ui';
-import {createElementSelectorModal} from '@/modules/element-selector-modal/registry';
+import {t, type ElementInfo} from '@craftcms/ui';
+import {createElementSelectorModal} from '@/modules/element-selector-modal/create-element-selector-modal';
 import '@craftcms/ui/components/disclosure/disclosure';
 import '@craftcms/ui/components/field-group/field-group';
 import {
@@ -33,15 +33,6 @@ export type LinkFieldValue = {
   value: string;
 };
 
-type ElementInfo = {
-  id: number | string;
-  label?: string;
-  siteId?: number | string;
-  $element?: {
-    data?: (key: string) => unknown;
-  };
-};
-
 type ElementSelectStartDetail = {
   restoreFocusTo?: HTMLElement;
   waitUntil: (promise: Promise<unknown>) => void;
@@ -176,9 +167,8 @@ class CraftLinkField extends LitElement {
       event.currentTarget instanceof HTMLElement ? event.currentTarget : null
     );
 
-    const modal = createElementSelectorModal(type.elementType, {
+    const modal = await createElementSelectorModal(type.elementType, {
       ...config,
-      closeOtherModals: false,
       hideOnSelect: true,
       modalTitle: t('Choose {type}', {type: type.label}),
       multiSelect: false,
@@ -189,15 +179,17 @@ class CraftLinkField extends LitElement {
           return;
         }
 
-        const siteId = element.siteId || element.$element?.data?.('site-id');
-        this.value = `{${type.refHandle}:${element.id}@${siteId}:url}`;
+        this.value = `{${type.refHandle}:${element.id}@${element.siteId}:url}`;
         this.defaultLabel = String(element.label || '');
         this.valueError = '';
       },
     });
 
-    modal.on('fadeOut', () => {
+    // The modal lives on <body>, outside this element's shadow root, so its DOM
+    // events never reach here — the controller is the subscription point.
+    modal.on('close', () => {
       this.dispatchElementSelectEvent('element-select-end');
+      modal.destroy();
     });
   }
 
diff --git a/resources/js/modules/markdown-field/behaviors/assets.ts b/resources/js/modules/markdown-field/behaviors/assets.ts
index 9daf72417d6..36970af9a9b 100644
--- a/resources/js/modules/markdown-field/behaviors/assets.ts
+++ b/resources/js/modules/markdown-field/behaviors/assets.ts
@@ -1,5 +1,8 @@
-import {t} from '@craftcms/ui';
-import {createElementSelectorModal} from '@/modules/element-selector-modal/registry';
+import {t, type ElementInfo} from '@craftcms/ui';
+import {
+  createElementSelectorModal,
+  type ElementSelectorModalHandle,
+} from '@/modules/element-selector-modal/create-element-selector-modal';
 import type {OverType as OverTypeInstance} from 'overtype';
 import type {PreviewController} from './preview';
 import {escapeMarkdownLabel} from './utilities';
@@ -7,21 +10,20 @@ import {escapeMarkdownLabel} from './utilities';
 const ASSET_ELEMENT_TYPE = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
 const ASSET_REF_HANDLE = 'asset';
 
-type AssetInfo = {
-  id: number | string;
-  label?: string;
-  siteId?: number | string;
-  $element?: {
-    data?: (key: string) => unknown;
-  };
-};
-
-type AssetSelectorModal = {
-  show: () => void;
+/**
+ * `kind` and `alt` come from `ModalIndexViewModel::typeSpecificRowData()`.
+ *
+ * They used to be read off the selected chip's data attributes, which the Vue
+ * index has none of — so every insert silently fell back to a link, even for
+ * images.
+ */
+type AssetInfo = ElementInfo & {
+  kind?: string | null;
+  alt?: string | null;
 };
 
 export type AssetController = {
-  open: () => void;
+  open: () => void | Promise<void>;
 };
 
 export function createAssetController(
@@ -30,40 +32,40 @@ export function createAssetController(
   assetSources: string[],
   preview: PreviewController
 ): AssetController {
-  let assetSelectorModal: AssetSelectorModal | null = null;
+  let assetSelectorModal: ElementSelectorModalHandle | null = null;
 
-  function open(): void {
+  async function open(): Promise<void> {
     if (!assetSelectorModal) {
-      assetSelectorModal = createElementSelectorModal(ASSET_ELEMENT_TYPE, {
-        closeOtherModals: false,
-        criteria: assetCriteria,
-        hideOnSelect: true,
-        modalTitle: t('Choose an asset'),
-        multiSelect: false,
-        onSelect: (assets: AssetInfo[]) => {
-          const [asset] = assets;
+      assetSelectorModal = await createElementSelectorModal(
+        ASSET_ELEMENT_TYPE,
+        {
+          closeOtherModals: false,
+          criteria: assetCriteria,
+          hideOnSelect: true,
+          modalTitle: t('Choose an asset'),
+          multiSelect: false,
+          onSelect: (assets: AssetInfo[]) => {
+            const [asset] = assets;
 
-          if (asset) {
-            insert(asset);
-          }
-        },
-        sources: assetSources,
-      });
+            if (asset) {
+              insert(asset);
+            }
+          },
+          sources: assetSources,
+        }
+      );
 
       return;
     }
 
-    assetSelectorModal.show();
+    void assetSelectorModal.show();
   }
 
   function insert(asset: AssetInfo): void {
-    const siteId = asset.siteId || asset.$element?.data?.('site-id');
-    const ref = `{${ASSET_REF_HANDLE}:${asset.id}@${siteId}:url}`;
-    const label = escapeMarkdownLabel(
-      String(asset.$element?.data?.('alt') || asset.label || '')
-    );
+    const ref = `{${ASSET_REF_HANDLE}:${asset.id}@${asset.siteId}:url}`;
+    const label = escapeMarkdownLabel(String(asset.alt || asset.label || ''));
     const markdown =
-      asset.$element?.data?.('kind') === 'image'
+      asset.kind === 'image'
         ? `![${label}](${ref})`
         : `[${label || ref}](${ref})`;
 
diff --git a/src/Http/ViewModels/ModalIndexViewModel.php b/src/Http/ViewModels/ModalIndexViewModel.php
index a6a149b8cc4..42a8c98d075 100644
--- a/src/Http/ViewModels/ModalIndexViewModel.php
+++ b/src/Http/ViewModels/ModalIndexViewModel.php
@@ -4,6 +4,7 @@
 
 namespace CraftCms\Cms\Http\ViewModels;
 
+use CraftCms\Cms\Asset\Elements\Asset;
 use CraftCms\Cms\Element\Contracts\ElementInterface;
 use CraftCms\Cms\Element\ElementSources;
 use CraftCms\Cms\Http\Requests\ElementIndexRequest;
@@ -53,9 +54,33 @@ protected function extraRowData(ElementInterface $element): array
             // Per element, not per type: an asset with no preview renders no thumb
             // even though its element type has them.
             'hasThumb' => $element->getThumbHtml(30) !== null,
+            ...$this->typeSpecificRowData($element),
         ];
     }
 
+    /**
+     * Metadata only some element types carry.
+     *
+     * The modal renders every element type through this one view model, so
+     * element-type view models (and their own `extraRowData()`) never run here.
+     * Callers that need more than the common keys — the Markdown field, which
+     * decides between an image embed and a link — would otherwise have no way to
+     * get it.
+     *
+     * @return array<string, mixed>
+     */
+    protected function typeSpecificRowData(ElementInterface $element): array
+    {
+        if ($element instanceof Asset) {
+            return [
+                'kind' => $element->kind,
+                'alt' => $element->alt,
+            ];
+        }
+
+        return [];
+    }
+
     /**
      * Unlike the index screens', these resolve in the `modal` context and honor
      * the opener's source restriction.

From f52937deb8473f8322b175349e141553af2c949d Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 07:25:20 -0500
Subject: [PATCH 18/24] Fix selection payload collisions and unresolved CpLink
 in the modal

---
 .../create-element-selector-modal.ts          | 18 +++++-
 .../useModalElementIndex.ts                   | 56 ++++++++-----------
 src/Http/ViewModels/ModalIndexViewModel.php   | 29 +++++++---
 3 files changed, 59 insertions(+), 44 deletions(-)

diff --git a/resources/js/modules/element-selector-modal/create-element-selector-modal.ts b/resources/js/modules/element-selector-modal/create-element-selector-modal.ts
index 7709d471e1a..e20a78bf103 100644
--- a/resources/js/modules/element-selector-modal/create-element-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/create-element-selector-modal.ts
@@ -90,11 +90,13 @@ export async function createElementSelectorModal(
   const [
     {createApp},
     {default: ElementSelectorModal},
-    {createCpComponentRegistry},
+    {cpComponentRegistry},
+    {default: CpLink},
   ] = await Promise.all([
     import('vue'),
     import('./ElementSelectorModal.vue'),
     import('@/bootstrap/components'),
+    import('@/common/components/CpLink.vue'),
   ]);
 
   const host = document.createElement('div');
@@ -102,7 +104,19 @@ export async function createElementSelectorModal(
   document.body.append(host);
 
   const app: App = createApp(ElementSelectorModal, {controller});
-  createCpComponentRegistry().install(app);
+
+  // The index renders server HTML through `DynamicHtmlRenderer`, which compiles
+  // it at runtime — so every component that HTML names has to be registered on
+  // *this* app. Title cells name `CpLink`, which lives on the CP app rather than
+  // in the registry, so it is registered explicitly alongside it.
+  //
+  // `cpComponentRegistry` is the shared singleton. The old modal called
+  // `createCpComponentRegistry()`, which builds an *empty* one — so nothing was
+  // ever registered and every title cell rendered as an inert `<cplink>`.
+  app.component('CpLink', CpLink);
+  cpComponentRegistry.install(app);
+  app.onUnmount(() => cpComponentRegistry.uninstall(app));
+
   app.config.compilerOptions.isCustomElement = (tag: string) =>
     tag.includes('-');
   app.mount(host);
diff --git a/resources/js/modules/element-selector-modal/useModalElementIndex.ts b/resources/js/modules/element-selector-modal/useModalElementIndex.ts
index 57bbfd97ae2..b2f16dad9bb 100644
--- a/resources/js/modules/element-selector-modal/useModalElementIndex.ts
+++ b/resources/js/modules/element-selector-modal/useModalElementIndex.ts
@@ -26,33 +26,15 @@ type Row = Record<string, any>;
 export type SelectedElement = ElementInfo;
 
 /**
- * Row keys carried through to the selection payload.
+ * The selection metadata `ModalIndexViewModel::extraRowData()` nests on each row.
  *
- * Not a blind spread of the row: a row is mostly rendered column HTML keyed by
- * attribute, and forwarding that would put kilobytes of markup into every
- * `onSelect` payload. These are the keys `ModalIndexViewModel::extraRowData()`
- * adds on purpose — `kind`/`alt` for the Markdown field, the folder keys for the
- * asset-move picker.
+ * Nested, not merged: the rest of a row is rendered column HTML keyed by
+ * attribute, and a flat merge let a column overwrite anything sharing its name —
+ * `status` arrived as a `<craft-badge>` element rather than `"pending"`. Reading
+ * one key also means no whitelist to keep in step with the server.
  */
-const EXTRA_ROW_KEYS = [
-  'kind',
-  'alt',
-  'isFolder',
-  'folderId',
-  'folderUrl',
-  'canMoveTo',
-] as const;
-
-function extraRowData(row: Row): Record<string, unknown> {
-  const extras: Record<string, unknown> = {};
-
-  for (const key of EXTRA_ROW_KEYS) {
-    if (row[key] !== undefined) {
-      extras[key] = row[key];
-    }
-  }
-
-  return extras;
+function elementInfo(row: Row): Record<string, unknown> {
+  return (row.elementInfo as Record<string, unknown> | undefined) ?? {};
 }
 
 interface Options {
@@ -194,15 +176,21 @@ export function useModalElementIndex(options: Options) {
    * because `onModalSelect` and `app/render-elements` both consume it.
    */
   const selectedElements = computed<SelectedElement[]>(() =>
-    table.getSelectedRowModel().rows.map(({original}) => ({
-      ...extraRowData(original),
-      id: Number(original.id),
-      siteId: original.siteId != null ? Number(original.siteId) : null,
-      label: String(original.label ?? original.title ?? original.id),
-      status: (original.status as string) ?? null,
-      url: (original.url as string) ?? null,
-      hasThumb: Boolean(original.hasThumb ?? original.thumb),
-    }))
+    table.getSelectedRowModel().rows.map(({original}) => {
+      const info = elementInfo(original);
+
+      return {
+        // Type-specific extras first — `kind`/`alt` for assets, `folderId` for
+        // folders — so the named keys below always win.
+        ...info,
+        id: Number(original.id),
+        siteId: info.siteId != null ? Number(info.siteId) : null,
+        label: String(info.label ?? original.id),
+        status: (info.status as string | null) ?? null,
+        url: (info.url as string | null) ?? null,
+        hasThumb: Boolean(info.hasThumb),
+      };
+    })
   );
 
   const hasSelection = computed(() => selectedElements.value.length > 0);
diff --git a/src/Http/ViewModels/ModalIndexViewModel.php b/src/Http/ViewModels/ModalIndexViewModel.php
index 42a8c98d075..92b45c89ec8 100644
--- a/src/Http/ViewModels/ModalIndexViewModel.php
+++ b/src/Http/ViewModels/ModalIndexViewModel.php
@@ -47,14 +47,24 @@ public function __construct(
     protected function extraRowData(ElementInterface $element): array
     {
         return [
-            'siteId' => $element->siteId,
-            'label' => $element->getUiLabel(),
-            'status' => $element->getStatus(),
-            'url' => $element->getUrl(),
-            // Per element, not per type: an asset with no preview renders no thumb
-            // even though its element type has them.
-            'hasThumb' => $element->getThumbHtml(30) !== null,
-            ...$this->typeSpecificRowData($element),
+            // Nested rather than merged into the row.
+            //
+            // `tableRows()` spreads extra row data *before* the visible columns,
+            // so any key that matches a column attribute is overwritten by that
+            // column's rendered HTML — `status` came back as a `<craft-badge>`,
+            // and `kind` would come back as "Image" rather than "image" whenever
+            // the File Kind column happened to be visible. A key of its own can't
+            // collide with a column name.
+            'elementInfo' => [
+                'siteId' => $element->siteId,
+                'label' => $element->getUiLabel(),
+                'status' => $element->getStatus(),
+                'url' => $element->getUrl(),
+                // Per element, not per type: an asset with no preview renders no
+                // thumb even though its element type has them.
+                'hasThumb' => $element->getThumbHtml(30) !== null,
+                ...$this->typeSpecificRowData($element),
+            ],
         ];
     }
 
@@ -75,6 +85,9 @@ protected function typeSpecificRowData(ElementInterface $element): array
             return [
                 'kind' => $element->kind,
                 'alt' => $element->alt,
+                // What the folder picker selects; the element's own id is the
+                // asset's, not the folder's.
+                ...($element->isFolder ? ['folderId' => $element->folderId] : []),
             ];
         }
 

From effa8cd12ca00b9c428d178ef5a53feaeb8b6314 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 07:45:17 -0500
Subject: [PATCH 19/24] Move the element select input onto the new selector
 modal

---
 resources/js/common/types/globals.d.ts        | 27 +++++++++++++++----
 .../base-element-select-input.ts              | 23 ++++++----------
 2 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/resources/js/common/types/globals.d.ts b/resources/js/common/types/globals.d.ts
index 5908e011cc2..5dea08645dd 100644
--- a/resources/js/common/types/globals.d.ts
+++ b/resources/js/common/types/globals.d.ts
@@ -80,22 +80,39 @@ interface SlideoutInstance {
 }
 
 interface ElementSelectorModalInstance {
-  show(): void;
-  on(event: string, callback: () => void): void;
+  show(): Promise<void>;
+  hide(): void;
+  destroy(): void;
+  /** Returns an unsubscribe function. */
+  on(event: string, callback: (data?: unknown) => void): () => void;
+  /** Republishes the whole set; the index re-reads it. */
+  setDisabledElementIds(ids: number[]): void;
+  setBusy(busy: boolean): void;
 }
 
 type FieldLayoutDesignerInstance = any;
 
 interface ElementSelectorModalSettings {
+  /** Accepted for compatibility; the native dialog manages stacking itself. */
   closeOtherModals?: boolean;
   criteria?: Record<string, unknown>;
   disabledElementIds?: number[];
+  disableElementsOnSelect?: boolean;
   hideOnSelect?: boolean;
   modalTitle?: string;
+  showTitle?: boolean;
+  selectBtnLabel?: string;
   multiSelect?: boolean;
-  onSelect?: (elements: any[]) => void;
-  showSiteMenu?: boolean;
+  /** May return a promise; the modal stays busy until it settles. */
+  onSelect?: (elements: any[], meta?: {transform?: string | null}) => unknown;
+  onCancel?: () => void;
+  onClose?: () => void;
+  showSiteMenu?: boolean | 'auto' | null;
+  siteIds?: number[] | null;
   sources?: string[] | null;
+  condition?: unknown;
+  storageKey?: string | null;
+  triggerElement?: HTMLElement | (() => HTMLElement | null) | null;
 }
 
 interface CraftStatic {
@@ -110,7 +127,7 @@ interface CraftStatic {
   createElementSelectorModal(
     elementType: string,
     settings?: ElementSelectorModalSettings
-  ): ElementSelectorModalInstance;
+  ): Promise<ElementSelectorModalInstance>;
   expandPostArray(arr: object): any;
   escapeHtml(str: string);
   sites: Site[];
diff --git a/resources/js/modules/element-select-input/base-element-select-input.ts b/resources/js/modules/element-select-input/base-element-select-input.ts
index 11409179e3e..f4983fc8375 100644
--- a/resources/js/modules/element-select-input/base-element-select-input.ts
+++ b/resources/js/modules/element-select-input/base-element-select-input.ts
@@ -939,7 +939,7 @@ export class BaseElementSelectInput extends Base {
     }
 
     if (this.modal) {
-      this.modal.show();
+      void this.modal.show();
 
       return;
     }
@@ -966,7 +966,7 @@ export class BaseElementSelectInput extends Base {
    */
   async createModal(): Promise<any> {
     const {createElementSelectorModal} =
-      await import('@/modules/element-selector-modal/registry');
+      await import('@/modules/element-selector-modal/create-element-selector-modal');
 
     return createElementSelectorModal(
       this.settings.elementType,
@@ -999,7 +999,9 @@ export class BaseElementSelectInput extends Base {
         siteIds: this.settings.siteIds,
         disabledElementIds: this.getDisabledElementIds(),
         onSelect: this.onModalSelect.bind(this),
-        onHide: this.onModalHide.bind(this),
+        // Was `onHide`; the controller calls this one whenever it closes,
+        // whether that came from Cancel, Escape or a completed selection.
+        onClose: this.onModalHide.bind(this),
         triggerElement: () => this.getNextLogicalFocusElement(),
         modalTitle: Craft.t('app', 'Choose'),
       },
@@ -1048,11 +1050,6 @@ export class BaseElementSelectInput extends Base {
   }
 
   async onModalSelect(elements: any[]): Promise<void> {
-    this.modal?.disable();
-    this.modal?.disableCancelBtn();
-    this.modal?.disableSelectBtn();
-    this.modal?.showFooterSpinner();
-
     this.elementEditor?.pause();
 
     const [inputUiType, inputUiSize] = (() => {
@@ -1134,10 +1131,8 @@ export class BaseElementSelectInput extends Base {
       this.updateDisabledElementsInModal();
     }
 
-    this.modal?.enable();
-    this.modal?.enableCancelBtn();
-    this.modal?.enableSelectBtn();
-    this.modal?.hideFooterSpinner();
+    // `busy` is the controller's, held across this method because it is the
+    // awaited `onSelect`. Only the close is ours to ask for.
     this.modal?.hide();
 
     await Craft.appendHeadHtml(data.headHtml);
@@ -1307,9 +1302,7 @@ export class BaseElementSelectInput extends Base {
    * enable or disable individual ids, so both directions are one assignment.
    */
   updateDisabledElementsInModal(): void {
-    if (this.modal) {
-      this.modal.settings.disabledElementIds = this.getDisabledElementIds();
-    }
+    this.modal?.setDisabledElementIds(this.getDisabledElementIds());
   }
 
   getElementById(id: number): any {

From 71cb247d4ba09c5b6841589ce74257e7407eb482 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 07:53:51 -0500
Subject: [PATCH 20/24] Add asset transform support to the selector modal

---
 .../ElementSelectorModal.test.ts              | 104 +++++++++++++++++-
 .../ElementSelectorModal.vue                  |  69 +++++++++++-
 .../modules/element-selector-modal/index.ts   |  18 ++-
 3 files changed, 184 insertions(+), 7 deletions(-)

diff --git a/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts b/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts
index 10a784c169c..47bdd559f4e 100644
--- a/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts
+++ b/resources/js/modules/element-selector-modal/ElementSelectorModal.test.ts
@@ -1,6 +1,11 @@
 import {createApp, defineComponent, h, nextTick} from 'vue';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vite-plus/test';
-import {ElementSelectorController, type ElementInfo} from '@craftcms/ui';
+import {
+  AssetSelectorController,
+  ElementSelectorController,
+  type AssetSelectorOptions,
+  type ElementInfo,
+} from '@craftcms/ui';
 
 /**
  * The real index pulls the whole element-index component tree and its
@@ -16,6 +21,28 @@ const stub = vi.hoisted(() => ({
   emit: null as ((event: string, payload?: unknown) => void) | null,
 }));
 
+const menu = vi.hoisted(() => ({
+  actions: null as any[] | null,
+}));
+
+vi.mock('@/common/components/ActionMenu.vue', async () => {
+  const {defineComponent: define, h: create} = await import('vue');
+
+  return {
+    default: define({
+      name: 'ActionMenuStub',
+      props: ['actions', 'label'],
+      setup(props) {
+        // Read inside render so each re-render republishes the current list.
+        return () => {
+          menu.actions = props.actions as any[];
+          return create('div', {class: 'action-menu-stub'});
+        };
+      },
+    }),
+  };
+});
+
 vi.mock('./ModalElementIndex.vue', async () => {
   const {defineComponent: define, h: create} = await import('vue');
 
@@ -87,6 +114,7 @@ beforeEach(() => {
   stub.clearSelection.mockClear();
   stub.lastProps = null;
   stub.emit = null;
+  menu.actions = null;
 });
 
 afterEach(() => {
@@ -205,3 +233,77 @@ describe('ElementSelectorModal', () => {
     expect(instance.index).toBeNull();
   });
 });
+
+describe('the transform menu', () => {
+  function assetController(
+    transforms: {handle: string; name: string}[],
+    options: Partial<AssetSelectorOptions> = {}
+  ) {
+    return new AssetSelectorController({
+      elementType: 'CraftCms\\Cms\\Asset\\Elements\\Asset',
+      transforms,
+      hideOnSelect: false,
+      loadIndexBody: async () => ({html: '', props: {}}),
+      fetchTransformUrl: async (id, handle) => `/t/${handle}/${id}.jpg`,
+      ...options,
+    });
+  }
+
+  it('is absent for a controller with no transforms', async () => {
+    const {host, unmount} = await mountModal(controller());
+
+    expect(host.querySelector('.action-menu-stub')).toBeNull();
+    unmount();
+  });
+
+  it('is absent for an asset controller that was given none', async () => {
+    const {host, unmount} = await mountModal(assetController([]));
+
+    expect(host.querySelector('.action-menu-stub')).toBeNull();
+    unmount();
+  });
+
+  it('offers one item per transform', async () => {
+    const instance = assetController([
+      {handle: 'thumb', name: 'Thumbnail'},
+      {handle: 'large', name: 'Large'},
+    ]);
+    const {host, unmount} = await mountModal(instance);
+
+    expect(host.querySelector('.action-menu-stub')).not.toBeNull();
+    expect(menu.actions!.map((a) => a.label)).toEqual(['Thumbnail', 'Large']);
+    unmount();
+  });
+
+  it('disables the items until something is selected', async () => {
+    // The invoker is frozen under `v-once`, so this is where reactivity has to
+    // land — a `disabled` on the invoker would never update.
+    const instance = assetController([{handle: 'thumb', name: 'Thumbnail'}]);
+    const {unmount} = await mountModal(instance);
+
+    expect(menu.actions!.every((a) => a.disabled)).toBe(true);
+
+    instance.setSelection([element(1)]);
+    await nextTick();
+
+    expect(menu.actions!.every((a) => a.disabled)).toBe(false);
+    unmount();
+  });
+
+  it('submits with the chosen transform applied', async () => {
+    const onSelect = vi.fn();
+    const instance = assetController([{handle: 'thumb', name: 'Thumbnail'}], {
+      onSelect,
+    });
+    const {unmount} = await mountModal(instance);
+
+    instance.setSelection([element(1)]);
+    await nextTick();
+    await menu.actions![0]!.onClick();
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect.mock.calls[0]![1]).toEqual({transform: 'thumb'});
+    expect(onSelect.mock.calls[0]![0][0].url).toBe('/t/thumb/1.jpg');
+    unmount();
+  });
+});
diff --git a/resources/js/modules/element-selector-modal/ElementSelectorModal.vue b/resources/js/modules/element-selector-modal/ElementSelectorModal.vue
index f9b9d0d123d..5d8107a4eb9 100644
--- a/resources/js/modules/element-selector-modal/ElementSelectorModal.vue
+++ b/resources/js/modules/element-selector-modal/ElementSelectorModal.vue
@@ -1,13 +1,39 @@
 <script setup lang="ts">
-  import {onMounted, onUnmounted, ref} from 'vue';
-  import type {ElementSelectorController} from '@craftcms/ui';
+  import {computed, onMounted, onUnmounted, ref} from 'vue';
+  import {t, type ElementSelectorController} from '@craftcms/ui';
   import '@craftcms/ui/components/element-selector-modal/element-selector-modal';
+  import ActionMenu from '@/common/components/ActionMenu.vue';
   import ModalElementIndex from './ModalElementIndex.vue';
   import type {SelectedElement} from './useModalElementIndex';
   import {useElementSelectorController} from './useElementSelectorController';
 
   const props = defineProps<{controller: ElementSelectorController}>();
 
+  /** The slice of `AssetSelectorController` this component needs. */
+  interface TransformCapable {
+    readonly transforms: readonly {handle: string; name: string}[];
+    selectWithTransform(handle: string): Promise<void>;
+  }
+
+  /**
+   * Duck-typed rather than `instanceof AssetSelectorController`.
+   *
+   * The controller may have been built from a different copy of the package
+   * (a plugin bundling its own), where `instanceof` quietly fails. The shape is
+   * the contract.
+   */
+  function asTransformCapable(candidate: unknown): TransformCapable | null {
+    const c = candidate as Partial<TransformCapable> | null;
+
+    return typeof c?.selectWithTransform === 'function' &&
+      Array.isArray(c.transforms) &&
+      c.transforms.length > 0
+      ? (c as TransformCapable)
+      : null;
+  }
+
+  const transformable = computed(() => asTransformCapable(props.controller));
+
   /**
    * No emits: the controller is the event bus.
    *
@@ -15,8 +41,25 @@
    * passes `onSelect`), which is also what the web component and the imperative
    * openers do. Re-emitting here would give one event two sources.
    */
-  const {indexBody, disabledElementIds} = useElementSelectorController(
-    props.controller
+  const {indexBody, disabledElementIds, selection} =
+    useElementSelectorController(props.controller);
+
+  /**
+   * The disabled state lives on the items, not the invoker.
+   *
+   * `ActionMenu` renders its invoker under `v-once` — mandatory, because
+   * `craft-action-menu` relocates its own light DOM and Vue re-patching it
+   * throws. A reactive `disabled` on the invoker would therefore never update,
+   * so the reactivity goes through the `actions` prop instead, which the web
+   * component consumes as data rather than as Vue-managed DOM.
+   */
+  const transformActions = computed(() =>
+    (transformable.value?.transforms ?? []).map((transform) => ({
+      label: transform.name,
+      disabled: selection.value.length === 0,
+      onClick: () =>
+        void transformable.value?.selectWithTransform(transform.handle),
+    }))
   );
 
   const index = ref<InstanceType<typeof ModalElementIndex> | null>(null);
@@ -50,5 +93,23 @@
       "
       @choose="() => controller.submit()"
     />
+
+    <!--
+      Assets only: pick a transform instead of plain Select. The controller
+      resolves each asset's transformed URL, then submits.
+    -->
+    <template v-if="transformable">
+      <ActionMenu
+        slot="primary-actions"
+        :actions="transformActions"
+        :label="t('Select transform')"
+      >
+        <template #invoker>
+          <craft-button type="button" variant="fill">
+            {{ t('Select transform') }}
+          </craft-button>
+        </template>
+      </ActionMenu>
+    </template>
   </craft-element-selector-modal>
 </template>
diff --git a/resources/js/modules/element-selector-modal/index.ts b/resources/js/modules/element-selector-modal/index.ts
index 74a2ce114d1..be4d32f58d4 100644
--- a/resources/js/modules/element-selector-modal/index.ts
+++ b/resources/js/modules/element-selector-modal/index.ts
@@ -1,5 +1,12 @@
 import {registerCraftGlobals} from '@/common/craft-global';
-import {t} from '@craftcms/ui';
+import {
+  AssetSelectorController,
+  adoptLegacyRegistrations as adoptLegacyControllerRegistrations,
+  hasElementSelectorController,
+  registerElementSelectorController,
+  t,
+} from '@craftcms/ui';
+import {createElementSelectorModal as createModal} from './create-element-selector-modal';
 import {BaseElementSelectorModal} from './base-element-selector-modal';
 import {AssetSelectorModal} from './asset-selector-modal';
 import {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
@@ -16,6 +23,7 @@ BaseElementSelectorModal.defaults.modalTitle ??= t('Select element');
 BaseElementSelectorModal.defaults.selectBtnLabel ??= t('Select');
 
 adoptLegacyRegistrations();
+adoptLegacyControllerRegistrations();
 
 // Skipped when something got there first, so a plugin can replace the built-in
 // asset modal without the duplicate-registration throw.
@@ -23,13 +31,19 @@ if (!hasElementSelectorModalClass(ASSET)) {
   registerElementSelectorModalClass(ASSET, AssetSelectorModal);
 }
 
+// Assets get transform support on the modern path. Same yield-to-a-plugin rule.
+if (!hasElementSelectorController(ASSET)) {
+  registerElementSelectorController(ASSET, AssetSelectorController);
+}
+
 // The classes stay on `Craft` for PHP-emitted boots (`new
 // Craft.VolumeFolderSelectorModal(…)`); the registry functions stay for plugins.
 registerCraftGlobals({
   BaseElementSelectorModal,
   AssetSelectorModal,
   VolumeFolderSelectorModal,
-  createElementSelectorModal,
+  // The modern factory: async, and returns a controller-backed handle.
+  createElementSelectorModal: createModal,
   registerElementSelectorModalClass,
 });
 

From 06068a5cec15074669e6ef08b908a54559332b6e Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 07:59:18 -0500
Subject: [PATCH 21/24] Document the element selector modal layers

---
 .../modules/element-selector-modal/README.md  | 127 ++++++++++++------
 1 file changed, 85 insertions(+), 42 deletions(-)

diff --git a/resources/js/modules/element-selector-modal/README.md b/resources/js/modules/element-selector-modal/README.md
index 363277c0258..c13ed5c992a 100644
--- a/resources/js/modules/element-selector-modal/README.md
+++ b/resources/js/modules/element-selector-modal/README.md
@@ -1,58 +1,101 @@
 # element-selector-modal
 
-Replaces `Craft.BaseElementSelectorModal` / `Craft.AssetSelectorModal` /
-`Craft.VolumeFolderSelectorModal` from the legacy cp bundle, plus the
-`createElementSelectorModal` / `registerElementSelectorModalClass` registry that
-used to live in `cp/src/js/Craft.js`.
+The Vue presentation layer for the element selector, plus what is left of the
+legacy modal it replaced.
 
-## Shape
+The business logic does **not** live here — it lives in
+`@craftcms/ui`'s [`core/element-selector`](../../../../packages/craftcms-ui/src/core/element-selector/),
+and the chrome lives in that package's `craft-element-selector-modal` component.
+This folder is the third of the three layers: the Vue view, the Vue-mounting
+factory, and the `Craft.*` shims.
 
-This module does **not** follow the `<name>.ce.ts` + `support.ts` shape described
-in [the modules README](../README.md). That pattern is for behavior wrapped
-around server-rendered markup; a selector modal has none — it is constructed
-imperatively and builds its own container. So there is no custom element and no
-element-keyed instance registry.
+## The three layers
 
-What does carry over is the rest of the pattern: the module owns the behavior,
-`window.Craft.*` is a shim, and the legacy source is deleted.
+```
+@craftcms/ui  core/element-selector/     ← no DOM, no Vue, no Lit, no jQuery
+                     │
+       ┌─────────────┴──────────────┐
+       ↓                            ↓
+@craftcms/ui                   this folder
+  <craft-element-selector-        ElementSelectorModal.vue
+   modal>  (chrome only)          (renders the WC, slots the index)
+```
+
+**The controller is the seam — not the slot.** The web component and the index
+never talk to each other; both talk to the controller. Every user intent goes
+*into* the controller, every piece of state comes *out* of it. The web
+component's Select button calls `controller.submit()` directly and *also*
+dispatches `craft-select` for onlookers — the event is a notification, not the
+mechanism. Wire it the other way and one intent ends up with two paths that
+drift.
+
+Corollary: `ModalElementIndex.vue` emits `selection-change` / `choose` and never
+imports the core. `ElementSelectorModal.vue` does the forwarding, which keeps the
+index reusable and `useModalElementIndex` core-agnostic.
+
+## Files
 
 | File | Role |
 | --- | --- |
-| `base-element-selector-modal.ts` | The base modal, on `@craftcms/garnish` `Modal`. |
-| `asset-selector-modal.ts` | Adds the "Select transform" menu. |
-| `volume-folder-selector-modal.ts` | Folder picker used by asset moves. |
-| `registry.ts` | Element type → modal class map, and the factory. |
-| `index.ts` | Registers the built-in asset mapping, assigns the `Craft.*` shims, re-exports. |
+| `ElementSelectorModal.vue` | The Vue view: renders `<craft-element-selector-modal>` with the index slotted in, plus the asset transform menu. |
+| `useElementSelectorController.ts` | Mirrors the core's `change` event into a `shallowRef`. Deliberately shallow — nothing wraps the controller's frozen snapshots in a reactive proxy, so Vue and the web component read the same object. |
+| `create-element-selector-modal.ts` | The imperative factory. Builds a controller from the registry, mounts the Vue view into a detached host, returns a handle. **Async**, and lazy-imports Vue so a page with a relation field doesn't pay for the index unless a modal opens. |
+| `ModalElementIndex.vue` | The index itself. Unchanged in shape from the legacy modal's. |
+| `useModalElementIndex.ts` | The composable behind it — the page's own `useElementIndex*` stack with a non-Inertia visitor. |
+| `modal-index-visitor.ts` | That visitor. |
+| `index.ts` | Registers the asset controller, drains legacy registrations, assigns the `Craft.*` shims. |
+| `volume-folder-selector-modal.ts` | **Still on the legacy modal.** See below. |
+| `base-element-selector-modal.ts`, `asset-selector-modal.ts`, `registry.ts` | **Legacy.** Only the volume-folder modal still reaches them. |
 
-## Registry
+## What the payload looks like
 
-`registry.ts` holds the map. `createElementSelectorModal(elementType, settings)`
-constructs the registered class, or `BaseElementSelectorModal`.
-`registerElementSelectorModalClass()` throws on a duplicate, as the legacy
-registry did.
+`onSelect` receives `ElementInfo[]` — the six stable keys plus whatever
+`ModalIndexViewModel::typeSpecificRowData()` adds for that element type
+(`kind`/`alt` for assets, `folderId` for folders).
 
-In-repo callers import the factory directly rather than going through `Craft`.
-The globals remain for plugins and for PHP-emitted boots — `MoveAssets.php` and
-the legacy `AssetIndex` still emit `new Craft.VolumeFolderSelectorModal(…)`.
+Those arrive **nested** under an `elementInfo` key on each row, not merged into
+it. A row is otherwise rendered column HTML keyed by attribute, and a flat merge
+let a column silently overwrite anything sharing its name — `status` came back as
+a `<craft-badge>` element rather than `"pending"`, and `kind` would have come back
+as `"Image"` rather than `"image"` whenever the File Kind column was visible.
 
-### Load order
+## The legacy remnant
+
+`volume-folder-selector-modal.ts` still extends `BaseElementSelectorModal`,
+because it drives the **legacy jQuery element index** rather than the Vue one:
+folder picking keys off the index's `sourcePath` (the breadcrumb of the folder
+you have navigated into), which is what "select the folder I'm looking at" means
+when no row is highlighted. It is the last thing keeping `ElementIndexHtml` and
+the HTML `element-indexes/*` endpoints alive.
+
+`VolumeFolderSelectorController` is already written and tested in the core, and
+`<craft-element-selector-modal>` has a `non-modal` mode for exactly this case —
+a top-layer dialog paints above `<body>`-appended menus, which is most of the
+legacy CP. What remains is the binder: create the element, slot
+`response.data.html` into it, boot `Craft.createElementIndex`, and adapt it to
+`VolumeFolderIndexAdapter`. Deleting the three legacy files falls out of that.
+
+## Registry
 
-The legacy bundle is a plain `<script>` and runs before this module, so a plugin
-can register a class before there is anywhere modern to put it.
-`adoptLegacyRegistrations()` drains anything sitting on
-`Craft._elementSelectorModalClasses` on load, and the built-in asset registration
-yields to an entry that is already there.
+The map lives in the core (`@craftcms/ui`, `registry.ts`) and is keyed to
+controller classes. `index.ts` registers `AssetSelectorController` for assets and
+drains anything a plugin left on `Craft._elementSelectorModalClasses` before this
+module evaluated — the legacy bundle is a plain `<script>` and runs first.
 
-That covers a plugin assigning into the object. A plugin *calling*
-`Craft.registerElementSelectorModalClass()` before this module evaluates will
-still fail — the function no longer exists in the legacy bundle. If that turns up
-in practice, the fix is a queueing stub in the legacy bundle, not moving the
-registry back.
+`Craft.createElementSelectorModal` is the modern factory, so it is now **async**
+and resolves to a handle rather than a modal object.
 
-## Still jQuery
+## Gotchas
 
-`base-element-selector-modal.ts` builds its chrome with jQuery (`$body`,
-`$footer`, `Craft.ui.createSubmitButton`) and binds the jQuery-synthetic
-`doubletap` event. The element index inside the modal is still the legacy
-`Craft.AssetIndex` / `BaseElementIndex` via the `Craft.createElementIndex` seam —
-the next registry worth porting the same way.
+- **The factory has to register `CpLink` on its app.** The index renders server
+  HTML through `DynamicHtmlRenderer`, which compiles at runtime, so every
+  component that HTML names must be registered on *that* app. `cpComponentRegistry`
+  is the shared singleton; `createCpComponentRegistry()` builds an empty one, and
+  calling it was why every title cell used to render as an inert `<cplink>`.
+- **`craft-action-menu` invokers must stay under `v-once`.** It relocates its own
+  light DOM, and Vue re-patching that throws `insertBefore` of null. The transform
+  menu therefore puts its reactive `disabled` on the *items* (a prop the web
+  component consumes as data), never on the invoker.
+- **`@craftcms/ui` is consumed two ways.** Vite dev reads its `src`; `vue-tsc`
+  resolves to `dist`. Run `npm run build:ui` after touching the package or the
+  root typecheck won't see it.

From 2f281e3770fd93358750686c2beb86d1591c5f1f Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 08:27:46 -0500
Subject: [PATCH 22/24] Retire the Garnish element selector modal

---
 .../element-selector-modal/controller-host.ts |   2 +-
 .../element-selector-modal.ts                 |   8 +-
 .../element-selector-controller.test.ts       |  27 +
 .../element-selector-controller.ts            |   7 +
 .../asset-selector-modal.ts                   | 183 ------
 .../base-element-selector-modal.test.ts       | 230 -------
 .../base-element-selector-modal.ts            | 622 ------------------
 .../element-selector-modal/index.test.ts      |  51 +-
 .../modules/element-selector-modal/index.ts   |  67 +-
 .../element-selector-modal/registry.test.ts   |  75 ---
 .../element-selector-modal/registry.ts        |  76 ---
 .../volume-folder-selector-modal.ts           | 416 ++++++++----
 12 files changed, 398 insertions(+), 1366 deletions(-)
 delete mode 100644 resources/js/modules/element-selector-modal/asset-selector-modal.ts
 delete mode 100644 resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts
 delete mode 100644 resources/js/modules/element-selector-modal/base-element-selector-modal.ts
 delete mode 100644 resources/js/modules/element-selector-modal/registry.test.ts
 delete mode 100644 resources/js/modules/element-selector-modal/registry.ts

diff --git a/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts b/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts
index 3139d9960fd..a343addc874 100644
--- a/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts
+++ b/packages/craftcms-ui/src/components/element-selector-modal/controller-host.ts
@@ -19,7 +19,7 @@ export class ElementSelectorHostController implements ReactiveController {
 
   constructor(
     private readonly host: ReactiveControllerHost,
-    private readonly source: () => ElementSelectorController | null
+    private readonly source: () => ElementSelectorController<any> | null
   ) {
     host.addController(this);
   }
diff --git a/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts
index 9be0d202bbd..a23f7b92b80 100644
--- a/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts
+++ b/packages/craftcms-ui/src/components/element-selector-modal/element-selector-modal.ts
@@ -54,9 +54,13 @@ export default class CraftElementSelectorModal extends CraftDialog {
   /**
    * The business layer. Set as a property, never constructed here — one
    * controller may be shared with a Vue view of the same modal.
+   *
+   * The adapter type is deliberately loose: the chrome never touches the index,
+   * so a subclass that narrows it (the folder picker, which requires a
+   * `sourcePath`) has to remain assignable here.
    */
-  @property({attribute: false}) controller: ElementSelectorController | null =
-    null;
+  @property({attribute: false})
+  controller: ElementSelectorController<any> | null = null;
 
   /** Show the heading. When false it stays in the a11y tree but is hidden. */
   @property({type: Boolean, attribute: 'show-title', reflect: true})
diff --git a/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts
index c1d0c245e1e..15c6ba04f2f 100644
--- a/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts
+++ b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.test.ts
@@ -517,6 +517,33 @@ describe('open and close', () => {
 });
 
 describe('destroy', () => {
+  it('leaves an idle state behind when destroyed mid-submit', async () => {
+    // The relation field destroys the modal from inside its own `onSelect`,
+    // which runs while `submit()` still holds `busy`.
+    let release: () => void = () => {};
+    const controller: ElementSelectorController = create({
+      hideOnSelect: false,
+      onSelect: () =>
+        new Promise<void>((resolve) => {
+          release = () => {
+            controller.destroy();
+            resolve();
+          };
+        }),
+    });
+    const states: boolean[] = [];
+    controller.on('change', (state) => states.push(state.busy));
+    controller.setSelection([element(1)]);
+
+    const pending = controller.submit();
+    expect(controller.state.busy).toBe(true);
+    release();
+    await pending;
+
+    expect(controller.state.busy).toBe(false);
+    expect(states[states.length - 1]).toBe(false);
+  });
+
   it('tears down the adapter and stops emitting', async () => {
     const controller = create();
     const index = stubIndex();
diff --git a/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts
index 8eae1c89706..4cd0601da43 100644
--- a/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts
+++ b/packages/craftcms-ui/src/core/element-selector/element-selector-controller.ts
@@ -167,6 +167,13 @@ export class ElementSelectorController<
     this.#selection = [];
     this.#indexBody = null;
     this.#open = false;
+    // Cleared too, so the last state anyone sees is idle. An opener that
+    // destroys the modal from inside `onSelect` gets here while `submit()` is
+    // still holding `busy`, and the release in its `finally` lands after
+    // `#listeners.clear()` — leaving a subscriber frozen mid-save.
+    this.#busy = false;
+    this.#loading = false;
+    this.#error = null;
     this.#update();
     this.#listeners.clear();
   }
diff --git a/resources/js/modules/element-selector-modal/asset-selector-modal.ts b/resources/js/modules/element-selector-modal/asset-selector-modal.ts
deleted file mode 100644
index 9774451954f..00000000000
--- a/resources/js/modules/element-selector-modal/asset-selector-modal.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-import {BaseElementSelectorModal} from './base-element-selector-modal';
-
-declare const Craft: any;
-declare const $: any;
-declare const Garnish: any;
-
-const DEFAULTS = {
-  canSelectImageTransforms: false,
-  transforms: [] as Array<{handle: string; name: string}>,
-};
-
-/**
- * AssetSelectorModal — a port of `Craft.AssetSelectorModal` onto
- * {@link BaseElementSelectorModal}. Adds an optional "Select transform" menu
- * button (using `Garnish.MenuBtn`) that lets the user pick an image transform
- * before selecting assets.
- *
- * Static `transformUrls` is preserved as a cross-instance URL cache, matching
- * the legacy class static property.
- */
-export class AssetSelectorModal extends BaseElementSelectorModal {
-  static override defaults =
-    DEFAULTS as typeof BaseElementSelectorModal.defaults & typeof DEFAULTS;
-
-  $selectTransformBtn: any = null;
-  _selectedTransform: string | null = null;
-
-  /** Cross-instance cache of transform URL lookups keyed by `[transform][elementId]`. */
-  static transformUrls: Record<string, Record<number, string | false>> = {};
-
-  constructor(elementType: string, settings?: any) {
-    super(elementType, settings);
-    if (new.target === AssetSelectorModal) {
-      this.init(elementType, settings);
-    }
-  }
-
-  override init(elementType: string, settings?: any): void {
-    settings = Object.assign({}, AssetSelectorModal.defaults, settings);
-    super.init(elementType, settings);
-
-    if (settings.transforms?.length) {
-      this.createSelectTransformButton(settings.transforms);
-    }
-  }
-
-  createSelectTransformButton(
-    transforms: Array<{handle: string; name: string}>
-  ): void {
-    if (!transforms?.length) return;
-
-    const $btnGroup = $('<div class="btngroup"/>').appendTo(
-      this.$primaryButtons
-    );
-    this.$selectBtn.appendTo($btnGroup);
-
-    this.$selectTransformBtn = $('<button/>', {
-      type: 'button',
-      class: 'btn menubtn disabled',
-      text: Craft.t('app', 'Select transform'),
-    }).appendTo($btnGroup);
-
-    const $menu = $('<div class="menu" data-align="right"></div>').insertAfter(
-      this.$selectTransformBtn
-    );
-    const $menuList = $('<ul></ul>').appendTo($menu);
-
-    for (const transform of transforms) {
-      $(
-        `<li><a data-transform="${transform.handle}">${transform.name}</a></li>`
-      ).appendTo($menuList);
-    }
-
-    const menuButton = new Garnish.MenuBtn(this.$selectTransformBtn, {
-      onOptionSelect: (option: Element) => this.onSelectTransform(option),
-    });
-    menuButton.disable();
-
-    this.$selectTransformBtn.data('menuButton', menuButton);
-  }
-
-  override onSelectionChange(): void {
-    const allowTransforms =
-      this.selectedElements.length > 0 && !!this.settings.transforms?.length;
-
-    const menuBtn = this.$selectTransformBtn?.data('menuButton') ?? null;
-
-    if (allowTransforms) {
-      menuBtn?.enable();
-      this.$selectTransformBtn?.removeClass('disabled');
-    } else if (this.$selectTransformBtn) {
-      menuBtn?.disable();
-      this.$selectTransformBtn.addClass('disabled');
-    }
-
-    super.onSelectionChange();
-  }
-
-  onSelectTransform(option: Element): void {
-    const transform = $(option).data('transform') as string;
-    this.selectImagesWithTransform(transform);
-  }
-
-  selectImagesWithTransform(transform: string): void {
-    if (typeof AssetSelectorModal.transformUrls[transform] === 'undefined') {
-      AssetSelectorModal.transformUrls[transform] = {};
-    }
-
-    const missingIds: number[] = [];
-
-    for (const element of this.selectedElements) {
-      const elementId = element.id;
-      if (
-        typeof AssetSelectorModal.transformUrls[transform][elementId] ===
-        'undefined'
-      ) {
-        missingIds.push(elementId);
-      }
-    }
-
-    if (missingIds.length) {
-      this.showFooterSpinner();
-      this.fetchMissingTransformUrls(missingIds, transform, () => {
-        this.hideFooterSpinner();
-        this.selectImagesWithTransform(transform);
-      });
-    } else {
-      this._selectedTransform = transform;
-      this.selectElements();
-      this._selectedTransform = null;
-    }
-  }
-
-  fetchMissingTransformUrls(
-    ids: number[],
-    transform: string,
-    callback: () => void
-  ): void {
-    const elementId = ids.pop()!;
-    // Ensure the transform bucket exists (may have been created in
-    // selectImagesWithTransform(), but guard here for safety).
-    AssetSelectorModal.transformUrls[transform] ??= {};
-    const bucket = AssetSelectorModal.transformUrls[transform]!;
-
-    Craft.sendActionRequest('POST', 'assets/generate-transform', {
-      data: {assetId: elementId, handle: transform},
-    })
-      .then((response: any) => {
-        bucket[elementId] = response.data.url || false;
-      })
-      .catch(() => {
-        bucket[elementId] = false;
-      })
-      .finally(() => {
-        if (ids.length) {
-          this.fetchMissingTransformUrls(ids, transform, callback);
-        } else {
-          callback();
-        }
-      });
-  }
-
-  override getElementInfo($selectedElements: any): any[] {
-    const info = super.getElementInfo($selectedElements);
-
-    if (this._selectedTransform) {
-      const cache =
-        AssetSelectorModal.transformUrls[this._selectedTransform] ?? {};
-      for (const item of info) {
-        const url = cache[item.id as number];
-        if (typeof url !== 'undefined' && url !== false) {
-          item.url = url;
-        }
-      }
-    }
-
-    return info;
-  }
-
-  override onSelect(elementInfo: any): void {
-    this.settings.onSelect(elementInfo, this._selectedTransform);
-  }
-}
diff --git a/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts b/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts
deleted file mode 100644
index 4da53e0f163..00000000000
--- a/resources/js/modules/element-selector-modal/base-element-selector-modal.test.ts
+++ /dev/null
@@ -1,230 +0,0 @@
-import {afterEach, expect, it, vi} from 'vite-plus/test';
-import $ from 'jquery';
-import {registerCraftGlobals} from '@/common/craft-global';
-import {BaseElementSelectorModal} from './base-element-selector-modal';
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-  document.body.replaceChildren();
-});
-
-it('retains inherited modal settings during initialization', () => {
-  const trigger = document.createElement('button');
-  document.body.append(trigger);
-  trigger.focus();
-
-  vi.stubGlobal('$', $);
-  // No `Craft.ui`: the chrome is built from Lit templates now, so nothing here
-  // reaches for the legacy jQuery button factories.
-  vi.stubGlobal('Craft', {
-    t: (_category: string, message: string) => message,
-  });
-
-  class TestModal extends BaseElementSelectorModal {
-    override show(): void {}
-  }
-
-  const modal = new TestModal('test');
-  modal.init('test', {resizable: false});
-
-  expect(modal.settings.hideOnEsc).toBe(true);
-  expect(modal.settings.minGutter).toBe(10);
-  expect(modal.settings.triggerElement).toBe(trigger);
-  expect(() => modal.onFadeOut()).not.toThrow();
-
-  modal.destroy();
-});
-
-function mountModal(settings: Record<string, any> = {}) {
-  vi.stubGlobal('$', $);
-  vi.stubGlobal('Craft', {
-    t: (_category: string, message: string) => message,
-  });
-
-  class TestModal extends BaseElementSelectorModal {
-    override show(): void {}
-  }
-
-  const modal = new TestModal('test');
-  modal.init('test', settings);
-
-  return {
-    modal,
-    container: document.querySelector<HTMLElement>(
-      '.modal.elementselectormodal'
-    )!,
-  };
-}
-
-it('renders the chrome the CP stylesheet expects', () => {
-  const {modal, container} = mountModal({
-    modalTitle: 'Choose an asset',
-    selectBtnLabel: 'Select',
-    showTitle: true,
-  });
-
-  const heading = container.querySelector('h1')!;
-  expect(heading.textContent).toBe('Choose an asset');
-  expect(container.getAttribute('aria-labelledby')).toBe(heading.id);
-  expect(heading.parentElement!.className).toBe('header');
-
-  expect(container.querySelector('.body > .spinner.big')).not.toBeNull();
-  expect(
-    container.querySelector('.footer > .buttons.left.secondary-buttons')
-  ).not.toBeNull();
-  expect(container.querySelector('.footer > .buttons.right')).not.toBeNull();
-
-  const cancelBtn = container.querySelector<HTMLButtonElement>(
-    'button[type="button"]'
-  )!;
-  expect(cancelBtn.className).toBe('btn');
-  expect(cancelBtn.textContent!.trim()).toBe('Cancel');
-
-  // Reproduces `Craft.ui.createSubmitButton({class: 'disabled', spinner: true})`
-  // — the CP stylesheet selects on every part of this.
-  const selectBtn = container.querySelector<HTMLButtonElement>(
-    'button[type="submit"]'
-  )!;
-  expect(selectBtn.className).toBe('btn disabled submit');
-  expect(selectBtn.getAttribute('aria-disabled')).toBe('true');
-  expect(
-    selectBtn.querySelector('.inline-flex.gap-xs > .label')!.textContent!.trim()
-  ).toBe('Select');
-  expect(selectBtn.querySelector('.spinner.spinner-absolute')).not.toBeNull();
-
-  // The `$`-prefixed fields stay jQuery wrappers around those same nodes,
-  // because subclasses and the element select input manipulate them.
-  expect(modal.$selectBtn[0]).toBe(selectBtn);
-  expect(modal.$cancelBtn[0]).toBe(cancelBtn);
-  expect(modal.$body[0]).toBe(container.querySelector('.body'));
-  expect(modal.$footer[0]).toBe(container.querySelector('.footer'));
-
-  modal.destroy();
-});
-
-it('hides the heading unless showTitle is set', () => {
-  const {modal, container} = mountModal({modalTitle: 'Choose'});
-
-  expect(container.querySelector('h1')!.parentElement!.className).toBe(
-    'visually-hidden'
-  );
-
-  modal.destroy();
-});
-
-it('preserves legacy Craft class extension', () => {
-  vi.stubGlobal('Craft', {});
-  registerCraftGlobals({BaseElementSelectorModal});
-
-  const RegisteredModal = window.Craft.BaseElementSelectorModal;
-  const ExtendedModal = RegisteredModal.extend({
-    init() {},
-    hasSelection() {
-      return !this.base();
-    },
-  });
-  const modal = new ExtendedModal();
-
-  expect(modal).toBeInstanceOf(BaseElementSelectorModal);
-  expect(modal.hasSelection()).toBe(true);
-  expect(ExtendedModal.ancestor).toBe(BaseElementSelectorModal);
-});
-
-it('exposes select button state controls to element select inputs', () => {
-  expect(
-    typeof Object.getOwnPropertyDescriptor(
-      BaseElementSelectorModal.prototype,
-      'enableSelectBtn'
-    )?.value
-  ).toBe('function');
-  expect(
-    typeof Object.getOwnPropertyDescriptor(
-      BaseElementSelectorModal.prototype,
-      'disableSelectBtn'
-    )?.value
-  ).toBe('function');
-});
-
-it('preserves legacy selector modal extension points', async () => {
-  vi.stubGlobal('Craft', {
-    registerElementSelectorModalClass: vi.fn(),
-    t: (_category: string, message: string) => message,
-  });
-
-  const {AssetSelectorModal} = await import('./asset-selector-modal');
-  const {VolumeFolderSelectorModal} =
-    await import('./volume-folder-selector-modal');
-  await import('./index');
-
-  registerCraftGlobals({
-    BaseElementSelectorModal,
-    AssetSelectorModal,
-    VolumeFolderSelectorModal,
-  });
-
-  expect((AssetSelectorModal as any).ancestor).toBe(BaseElementSelectorModal);
-  expect((VolumeFolderSelectorModal as any).ancestor).toBe(
-    BaseElementSelectorModal
-  );
-
-  for (const method of [
-    'sidebarShouldBeHidden',
-    'resetView',
-    'buildSidebarToggleView',
-    'sidebarIsOpen',
-    'toggleSidebar',
-    'openSidebar',
-    'closeSidebar',
-    'getActiveSourceName',
-    'updateHeading',
-  ]) {
-    expect((BaseElementSelectorModal.prototype as any)[method]).toBeTypeOf(
-      'function'
-    );
-  }
-
-  for (const method of [
-    'createSelectTransformButton',
-    'onSelectTransform',
-    'selectImagesWithTransform',
-    'fetchMissingTransformUrls',
-  ]) {
-    expect((AssetSelectorModal.prototype as any)[method]).toBeTypeOf(
-      'function'
-    );
-  }
-
-  expect(BaseElementSelectorModal.defaults).toMatchObject({
-    fullscreen: false,
-    resizable: true,
-    hideOnSelect: true,
-    indexSettings: {},
-    modalTitle: 'Select element',
-    selectBtnLabel: 'Select',
-  });
-  expect(AssetSelectorModal.defaults).toMatchObject({
-    canSelectImageTransforms: false,
-    transforms: [],
-  });
-  expect(VolumeFolderSelectorModal.defaults).toMatchObject({
-    disabledFolderIds: [],
-    indexSettings: {},
-  });
-
-  class UninitializedModal extends BaseElementSelectorModal {}
-
-  const modal = new UninitializedModal('test');
-  for (const property of [
-    '$sources',
-    '$sourceToggles',
-    '$sidebarToggleBtn',
-    '$sidebarCloseBtn',
-    '$mainHeading',
-    '$search',
-    '$elements',
-    '$tbody',
-  ]) {
-    expect(property in modal).toBe(true);
-  }
-  modal.destroy();
-});
diff --git a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts b/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
deleted file mode 100644
index 5fa27c7edd5..00000000000
--- a/resources/js/modules/element-selector-modal/base-element-selector-modal.ts
+++ /dev/null
@@ -1,622 +0,0 @@
-import {
-  Modal,
-  ESC_KEY,
-  isMobileBrowser,
-  bod,
-  type ModalSettings,
-} from '@craftcms/garnish';
-import {html, render, type TemplateResult} from 'lit';
-import type {App} from 'vue';
-import type {SelectedElement} from './useModalElementIndex';
-import {ref} from 'lit/directives/ref.js';
-import {uiLayerManager} from '@/modules/slideout/slideout';
-
-declare const Craft: any;
-declare const $: any;
-
-const noop = () => {};
-
-/** What `ModalElementIndex` exposes back to the modal shell. */
-type ModalElementIndexInstance = {
-  clearSelection(): void;
-};
-
-// Non-runtime-dependent defaults, separated so the static getter can augment them.
-const BASE_DEFAULTS = {
-  // Modal settings preserved after we overwrite this.settings in init()
-  resizable: true,
-  hideOnShadeClick: true,
-  // Modal lifecycle callbacks so super.onFadeIn/onShow/onHide don't throw
-  onFadeIn: noop,
-  onShow: noop,
-  onHide: noop,
-  // Craft-specific defaults
-  fullscreen: false,
-  storageKey: null as string | null,
-  sources: null as string[] | null,
-  condition: null as any,
-  referenceElementId: null as number | null,
-  referenceElementOwnerId: null as number | null,
-  referenceElementSiteId: null as number | null,
-  criteria: null as Record<string, any> | null,
-  multiSelect: false,
-  showSiteMenu: null as boolean | string | null,
-  siteIds: null as number[] | null,
-  disabledElementIds: [] as number[],
-  disableElementsOnSelect: false,
-  hideOnSelect: true,
-  modalTitle: null as string | null,
-  showTitle: false,
-  selectBtnLabel: null as string | null,
-  onCancel: noop,
-  onSelect: noop as (elementInfo: any, ...args: any[]) => void,
-  hideSidebar: false,
-  defaultSiteId: null as number | null,
-  defaultSource: null as string | null,
-  defaultSourcePath: null as string | null,
-  preferStoredSource: false,
-  showSourcePath: true,
-  bodyAction: 'element-selector-modals/body',
-  indexSettings: {} as Record<string, any>,
-};
-
-/**
- * BaseElementSelectorModal — a port of `Craft.BaseElementSelectorModal` onto the
- * modern `@craftcms/garnish` `Modal`. Loads an element index into a modal via a
- * server action, then lets the user select elements and fires `onSelect`.
- *
- * Its own chrome is built with Lit templates (`chromeTemplate()`,
- * `buildSidebarToggleView()`); the `$`-prefixed fields are jQuery wrappers around
- * those nodes, since subclasses and the element select input manipulate them.
- *
- * The modal shell is modern (`extends Modal`), but element-index interaction
- * retains the jQuery seam: the still-legacy `Craft.createElementIndex` produces
- * jQuery-based DOM, and the `doubletap` / activate events on that DOM are jQuery
- * synthetic events that must be bound via `$(el).on(...)`, NOT `addListener`
- * (which uses native `addEventListener` and would not receive jQuery-triggered
- * events).
- */
-export class BaseElementSelectorModal extends Modal {
-  static override defaults: ModalSettings & typeof BASE_DEFAULTS =
-    Object.assign({}, Modal.defaults, BASE_DEFAULTS);
-
-  // Shadows Modal's typed `settings` so we can store our own key/value shape.
-  declare settings: any;
-
-  // Not a static `defaults` override of Modal's typed defaults — we use a
-  // module-level constant (BASE_DEFAULTS) and resolve Craft.t() values lazily
-  // in init() where Craft is guaranteed available.
-
-  elementType: string | null = null;
-  /** The mounted Vue index, and the app hosting it. */
-  index: ModalElementIndexInstance | null = null;
-  indexApp: App | null = null;
-  /** Pushed up by the index whenever its selection changes. */
-  selectedElements: SelectedElement[] = [];
-  supportSidebarToggleView = false;
-
-  // jQuery refs to modal DOM — accessed by subclasses and external code.
-  $body: any = null;
-  $content: any = null;
-  $footer: any = null;
-  $selectBtn: any = null;
-  $sidebar: any = null;
-  $sources: any = null;
-  $sourceToggles: any = null;
-  $search: any = null;
-  $elements: any = null;
-  $tbody: any = null;
-  $primaryButtons: any = null;
-  $secondaryButtons: any = null;
-  $cancelBtn: any = null;
-  $main: any = null;
-
-  $mainHeader: any = null;
-  $sidebarHeader: any = null;
-  $sidebarCloseBtn: any = null;
-  $sidebarToggleBtn: any = null;
-  $mainHeading: any = null;
-
-  constructor(elementType: string, settings?: any) {
-    // Construct Modal shell without a container and without auto-showing.
-    // The actual container is built in init() and handed to setContainer().
-    super(undefined, {autoShow: false});
-    if (new.target === BaseElementSelectorModal) {
-      this.init(elementType, settings);
-    }
-  }
-
-  init(elementType: string, settings?: any): void {
-    this.elementType = elementType;
-
-    // Merge user settings over our defaults (resolves Craft.t() lazily here,
-    // not at module load time where Craft may not exist yet).
-    this.settings = Object.assign(
-      {},
-      BaseElementSelectorModal.defaults,
-      this.settings,
-      {
-        modalTitle:
-          BaseElementSelectorModal.defaults.modalTitle ??
-          Craft.t('app', 'Select element'),
-        selectBtnLabel:
-          BaseElementSelectorModal.defaults.selectBtnLabel ??
-          Craft.t('app', 'Select'),
-      },
-      settings
-    );
-
-    const headingId =
-      'elementSelectorModalHeading-' + Math.floor(Math.random() * 1000000);
-
-    // The container is created by hand rather than by the template: `render()`
-    // owns its container's children, and `setContainer()` needs an element that
-    // outlives the render.
-    const container = document.createElement('div');
-    container.className = 'modal elementselectormodal';
-    container.setAttribute('aria-labelledby', headingId);
-
-    if (this.settings.fullscreen) {
-      container.classList.add('fullscreen');
-      this.settings.minGutter = 0;
-    }
-
-    render(this.chromeTemplate(headingId), container);
-    bod.append(container);
-    this.setContainer(container);
-
-    // Use native click — <button> fires click on keyboard activation natively.
-    this.addListener(this.$cancelBtn[0], 'click', () => this.cancel());
-    this.addListener(this.$selectBtn[0], 'click', () => this.selectElements());
-
-    this.show();
-  }
-
-  /**
-   * The modal's own chrome — heading, body, footer and the two footer buttons.
-   *
-   * The `$`-prefixed fields stay jQuery objects: subclasses and the element
-   * select input reach for them (`$primaryButtons.append(…)`,
-   * `$selectBtn.addClass('loading')`), so only their construction moves here.
-   *
-   * The select button reproduces what `Craft.ui.createSubmitButton()` emits —
-   * `btn submit`, a `.label` inside an `.inline-flex` wrapper, and an absolutely
-   * positioned spinner — because the CP stylesheet selects on all three.
-   */
-  protected chromeTemplate(headingId: string): TemplateResult {
-    return html`
-      <div class=${this.settings.showTitle ? 'header' : 'visually-hidden'}>
-        <h1 id=${headingId}>${this.settings.modalTitle}</h1>
-      </div>
-      <div class="body" ${ref((el) => (this.$body = $(el)))}>
-        <div class="spinner big"></div>
-      </div>
-      <div class="footer" ${ref((el) => (this.$footer = $(el)))}>
-        <div
-          class="buttons left secondary-buttons"
-          ${ref((el) => (this.$secondaryButtons = $(el)))}
-        ></div>
-        <div
-          class="buttons right"
-          ${ref((el) => (this.$primaryButtons = $(el)))}
-        >
-          <button
-            type="button"
-            class="btn"
-            ${ref((el) => (this.$cancelBtn = $(el)))}
-          >
-            ${Craft.t('app', 'Cancel')}
-          </button>
-          <button
-            type="submit"
-            class="btn disabled submit"
-            aria-disabled="true"
-            ${ref((el) => (this.$selectBtn = $(el)))}
-          >
-            <div class="inline-flex gap-xs">
-              <div class="label">${this.settings.selectBtnLabel}</div>
-            </div>
-            <div class="spinner spinner-absolute"></div>
-          </button>
-        </div>
-      </div>
-    `;
-  }
-
-  /**
-   * Renders a template and hands back its root element, detached.
-   *
-   * For markup that has to be inserted into DOM this class doesn't own — the
-   * element index's sidebar and main column, which the legacy index renders.
-   * `render()` would claim those containers and wipe them, so the template is
-   * rendered into a throwaway host and its root moved out. Safe only because
-   * none of these are ever re-rendered.
-   */
-  protected renderElement(template: TemplateResult): HTMLElement {
-    const host = document.createElement('div');
-    render(template, host);
-
-    return host.firstElementChild as HTMLElement;
-  }
-
-  updateModalBottomPadding(): void {
-    const footerHeight = this.$footer.outerHeight();
-    const bottomPadding = parseInt($(this.$container).css('padding-bottom'));
-    if (footerHeight !== bottomPadding) {
-      $(this.$container).css('padding-bottom', footerHeight);
-    }
-  }
-
-  updateSidebarView(): void {
-    if (!this.supportSidebarToggleView) return;
-
-    if (this.sidebarShouldBeHidden()) {
-      if (!this.$sidebarToggleBtn) this.buildSidebarToggleView();
-    } else {
-      if (this.$sidebarToggleBtn) this.resetView();
-    }
-  }
-
-  sidebarShouldBeHidden(): boolean {
-    return $(this.$container).outerWidth() < 550;
-  }
-
-  resetView(): void {
-    this.$mainHeader?.remove();
-    this.$sidebarHeader?.remove();
-    this.$sidebarToggleBtn = null;
-    this.$body.addClass('has-sidebar');
-    this.$content.addClass('has-sidebar');
-    this.$sidebar.removeClass('hidden');
-  }
-
-  buildSidebarToggleView(): void {
-    if (this.$sidebarToggleBtn || !this.sidebarShouldBeHidden()) return;
-
-    // `btn-empty` and the missing `btn` reproduce what `Craft.ui.createButton()`
-    // plus the `.removeClass('btn')` these two always did emit: an icon-only
-    // button that takes its appearance from `nav-close` / `nav-toggle`.
-    const sidebarHeader = this.renderElement(html`
-      <div class="sidebar-header">
-        <button
-          type="button"
-          class="nav-close close-btn btn-empty"
-          aria-label=${Craft.t('app', 'Close')}
-          ${ref((el) => (this.$sidebarCloseBtn = $(el)))}
-        ></button>
-      </div>
-    `);
-    this.$sidebar[0].prepend(sidebarHeader);
-    this.$sidebarHeader = $(sidebarHeader);
-
-    const mainHeader = this.renderElement(html`
-      <div class="main-header">
-        <h2 class="main-heading" ${ref((el) => (this.$mainHeading = $(el)))}>
-          ${this.getActiveSourceName()}
-        </h2>
-        <button
-          type="button"
-          class="nav-toggle btn-empty"
-          aria-expanded="false"
-          aria-controls="modal-sidebar"
-          aria-label=${Craft.t('app', 'Show sidebar')}
-          ${ref((el) => (this.$sidebarToggleBtn = $(el)))}
-        ></button>
-      </div>
-    `);
-    this.$main[0].prepend(mainHeader);
-    this.$mainHeader = $(mainHeader);
-
-    this.$sidebar.attr('id', 'modal-sidebar');
-    this.closeSidebar();
-
-    this.addListener(this.$sidebarToggleBtn[0], 'click', () =>
-      this.toggleSidebar()
-    );
-    this.addListener(this.$sidebarCloseBtn[0], 'click', () =>
-      this.toggleSidebar()
-    );
-  }
-
-  sidebarIsOpen(): boolean {
-    return this.$sidebarToggleBtn?.attr('aria-expanded') === 'true';
-  }
-
-  toggleSidebar(): void {
-    if (this.sidebarIsOpen()) {
-      this.closeSidebar();
-    } else {
-      this.openSidebar();
-    }
-  }
-
-  openSidebar(): void {
-    this.$body.addClass('has-sidebar');
-    this.$content.addClass('has-sidebar');
-    this.$sidebar.removeClass('hidden');
-    this.$sidebarToggleBtn.attr('aria-expanded', 'true');
-    this.$sidebar.find(':focusable').first().focus();
-
-    uiLayerManager().addLayer(this.$sidebar[0]);
-    uiLayerManager().registerShortcut(ESC_KEY, () => {
-      this.closeSidebar();
-    });
-  }
-
-  closeSidebar(): void {
-    if (!this.$sidebarToggleBtn) return;
-
-    if (this.sidebarIsOpen()) {
-      uiLayerManager().removeLayer();
-    }
-
-    this.$sidebar.addClass('hidden');
-    this.$sidebarToggleBtn.attr('aria-expanded', 'false');
-
-    const focusedEl = document.activeElement;
-    if (focusedEl && this.$sidebar[0].contains(focusedEl)) {
-      this.$sidebarToggleBtn.focus();
-    }
-
-    this.$body.removeClass('has-sidebar');
-    this.$content.removeClass('has-sidebar');
-  }
-
-  getActiveSourceName(): string {
-    return this.$sidebar.find('.sel').text();
-  }
-
-  override onFadeIn(): void {
-    if (!this.index) {
-      this._createElementIndex();
-    } else {
-      this.updateModalBottomPadding();
-    }
-    super.onFadeIn();
-  }
-
-  onSelectionChange(): void {
-    this.updateSelectBtnState();
-  }
-
-  onSelectSource(): void {
-    this.updateHeading();
-    this.updateModalBottomPadding();
-  }
-
-  updateHeading(): void {
-    if (!this.$mainHeading) return;
-    this.$mainHeading.text(this.getActiveSourceName());
-  }
-
-  updateSelectBtnState(): void {
-    if (this.$selectBtn) {
-      if (this.shouldEnableSelectBtn()) {
-        this.enableSelectBtn();
-      } else {
-        this.disableSelectBtn();
-      }
-    }
-  }
-
-  shouldEnableSelectBtn(): boolean {
-    return this.hasSelection();
-  }
-
-  hasSelection(): boolean {
-    return this.selectedElements.length > 0;
-  }
-
-  enableSelectBtn(): void {
-    this.$selectBtn.removeClass('disabled').attr('aria-disabled', 'false');
-  }
-
-  disableSelectBtn(): void {
-    this.$selectBtn.addClass('disabled').attr('aria-disabled', 'true');
-  }
-
-  enableCancelBtn(): void {
-    this.$cancelBtn.removeClass('disabled');
-  }
-
-  disableCancelBtn(): void {
-    this.$cancelBtn.addClass('disabled');
-  }
-
-  showFooterSpinner(): void {
-    this.$selectBtn.addClass('loading');
-  }
-
-  hideFooterSpinner(): void {
-    this.$selectBtn.removeClass('loading');
-  }
-
-  cancel(): void {
-    if (!this.$cancelBtn.hasClass('disabled')) {
-      this.hide();
-    }
-  }
-
-  selectElements(): void {
-    if (!this.hasSelection()) {
-      return;
-    }
-
-    const elementInfo = this.getElementInfo(this.selectedElements);
-
-    this.onSelect(elementInfo);
-
-    if (this.settings.disableElementsOnSelect) {
-      // Selected elements become unselectable, so the same one can't be picked
-      // twice while the modal stays open.
-      this.settings.disabledElementIds = [
-        ...(this.settings.disabledElementIds ?? []),
-        ...this.selectedElements.map((element) => element.id),
-      ];
-      this.index?.clearSelection();
-    }
-
-    if (this.settings.hideOnSelect) {
-      this.hide();
-    }
-  }
-
-  /**
-   * Hook for subclasses to adjust what gets handed to `onSelect` — the asset
-   * modal splices a transformed URL in here.
-   *
-   * These arrive as plain objects from the index rather than being read back
-   * off chip data attributes, but carry the same keys `Craft.getElementInfo()`
-   * produced, since the relation field consumes them either way.
-   */
-  getElementInfo(elements: SelectedElement[]): any[] {
-    return elements.map((element) => ({...element}));
-  }
-
-  override onShow(): void {
-    this.updateSelectBtnState();
-
-    // Resize listeners are added fresh each show since Modal.hide() removes
-    // all listeners registered via addListener in legacy Garnish. In modern
-    // Garnish they are not removed on hide, but re-adding is idempotent
-    // provided we track and clear them properly — for simplicity we keep the
-    // legacy pattern of adding per-show.
-    this.addListener(window, 'resize', () => this.updateSidebarView());
-    this.addListener(window, 'resize', () => this.updateModalBottomPadding());
-
-    this.updateModalBottomPadding();
-    this.updateSidebarView();
-
-    super.onShow();
-  }
-
-  override onHide(): void {
-    this.closeSidebar();
-    super.onHide();
-  }
-
-  /**
-   * The index is a Vue app rather than markup the modal owns, so it has to be
-   * unmounted explicitly — `Modal.destroy()` only clears the container.
-   */
-  override destroy(): void {
-    this.indexApp?.unmount();
-    this.indexApp = null;
-    this.index = null;
-    this.selectedElements = [];
-
-    super.destroy();
-  }
-
-  onSelect(elementInfo: any): void {
-    this.settings.onSelect(elementInfo);
-  }
-
-  override disable(): void {
-    super.disable();
-  }
-
-  override enable(): void {
-    super.enable();
-  }
-
-  getElementIndexParams(): Record<string, any> {
-    const params: Record<string, any> = {
-      context: 'modal',
-      elementType: this.elementType,
-      sources: this.settings.sources,
-      condition: this.settings.condition,
-    };
-
-    if (
-      this.settings.showSiteMenu !== null &&
-      this.settings.showSiteMenu !== 'auto'
-    ) {
-      params.showSiteMenu = this.settings.showSiteMenu ? '1' : '0';
-    }
-
-    if (this.settings.siteIds) {
-      params.siteIds = this.settings.siteIds;
-    }
-
-    return params;
-  }
-
-  _createElementIndex(): void {
-    Craft.sendActionRequest('POST', this.settings.bodyAction, {
-      data: this.getElementIndexParams(),
-    }).then(async (response: any) => {
-      // Loaded on open, not at module scope: this pulls Vue and the whole
-      // element index component tree, which every page carrying a relation
-      // field would otherwise pay for whether or not a modal is ever opened.
-      const [
-        {createApp},
-        {default: ModalElementIndex},
-        {createCpComponentRegistry},
-      ] = await Promise.all([
-        import('vue'),
-        import('./ModalElementIndex.vue'),
-        import('@/bootstrap/components'),
-      ]);
-
-      this.$body.empty();
-      this.$content = this.$body;
-
-      const host = document.createElement('div');
-      host.className = 'modal-index-host';
-      this.$body[0].append(host);
-
-      this.indexApp = createApp(ModalElementIndex, {
-        url: Craft.getActionUrl(this.settings.bodyAction),
-        initial: response.data.props,
-        params: this.getElementIndexParams(),
-        disabledElementIds: this.settings.disabledElementIds ?? [],
-        onSelectionChange: (elements: SelectedElement[]) => {
-          this.selectedElements = elements;
-          this.onSelectionChange();
-        },
-        onChoose: () => this.selectElements(),
-      });
-
-      createCpComponentRegistry().install(this.indexApp);
-      this.indexApp.config.compilerOptions.isCustomElement = (tag: string) =>
-        tag.includes('-');
-      this.index = this.indexApp.mount(
-        host
-      ) as unknown as ModalElementIndexInstance;
-
-      this.updateModalBottomPadding();
-      this.updateSelectBtnState();
-    });
-  }
-
-  getIndexSettings(): Record<string, any> {
-    return Object.assign(
-      {
-        context: 'modal',
-        modal: this,
-        storageKey: this.settings.storageKey,
-        condition: this.settings.condition,
-        referenceElementId: this.settings.referenceElementId,
-        referenceElementOwnerId: this.settings.referenceElementOwnerId,
-        referenceElementSiteId: this.settings.referenceElementSiteId,
-        criteria: Object.assign({}, this.settings.criteria),
-        disabledElementIds: this.settings.disabledElementIds,
-        selectable: true,
-        multiSelect: this.settings.multiSelect,
-        waitForDoubleClicks: true,
-        buttonContainer: this.$secondaryButtons,
-        onSelectionChange: () => this.onSelectionChange(),
-        onSourcePathChange: () => this.onSelectionChange(),
-        onSelectSource: this.onSelectSource.bind(this),
-        hideSidebar: this.settings.hideSidebar,
-        defaultSiteId: this.settings.defaultSiteId,
-        defaultSource: this.settings.defaultSource,
-        defaultSourcePath: this.settings.defaultSourcePath,
-        preferStoredSource: this.settings.preferStoredSource,
-        showSourcePath: this.settings.showSourcePath,
-      },
-      this.settings.indexSettings
-    );
-  }
-}
diff --git a/resources/js/modules/element-selector-modal/index.test.ts b/resources/js/modules/element-selector-modal/index.test.ts
index 05a1234b6d1..a86a2891f20 100644
--- a/resources/js/modules/element-selector-modal/index.test.ts
+++ b/resources/js/modules/element-selector-modal/index.test.ts
@@ -1,4 +1,23 @@
-import {afterEach, expect, it, vi} from 'vite-plus/test';
+import {afterEach, beforeEach, expect, it, vi} from 'vite-plus/test';
+
+const ASSET = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
+
+/**
+ * Imports the module under test and the registry it writes into, together.
+ *
+ * The registry is a module singleton in `@craftcms/ui`, and `vi.resetModules()`
+ * hands each test a fresh module graph — so the registry has to be read from the
+ * *same* graph as `./index`, not from a stale top-level import.
+ */
+async function importModule() {
+  await import('./index');
+
+  return import('@craftcms/ui');
+}
+
+beforeEach(() => {
+  vi.resetModules();
+});
 
 afterEach(() => {
   vi.unstubAllGlobals();
@@ -8,29 +27,27 @@ afterEach(() => {
 it('owns the registry rather than reaching into the legacy bundle', async () => {
   vi.stubGlobal('Craft', {});
 
-  const module = await import('./index');
+  const {AssetSelectorController, elementSelectorControllerClass} =
+    await importModule();
   const Craft = (window as any).Craft;
 
-  // The factory and the registration hook now come from here, so the legacy
-  // bundle no longer has to ship either.
+  // The factory and the registration hook come from here, so the legacy bundle
+  // no longer has to ship either.
   expect(typeof Craft.createElementSelectorModal).toBe('function');
-  expect(typeof Craft.registerElementSelectorModalClass).toBe('function');
-  expect(
-    module.elementSelectorModalClass('CraftCms\\Cms\\Asset\\Elements\\Asset')
-  ).toBe(module.AssetSelectorModal);
+  expect(typeof Craft.registerElementSelectorController).toBe('function');
+  // Still constructible from PHP-emitted boots.
+  expect(typeof Craft.VolumeFolderSelectorModal).toBe('function');
+
+  expect(elementSelectorControllerClass(ASSET)).toBe(AssetSelectorController);
 });
 
-it('yields to a modal class the legacy bundle already registered for assets', async () => {
-  class PluginAssetModal {}
+it('yields to a controller the legacy bundle already registered for assets', async () => {
+  class PluginAssetController {}
   vi.stubGlobal('Craft', {
-    _elementSelectorModalClasses: {
-      'CraftCms\\Cms\\Asset\\Elements\\Asset': PluginAssetModal,
-    },
+    _elementSelectorModalClasses: {[ASSET]: PluginAssetController},
   });
 
-  const module = await import('./index');
+  const {elementSelectorControllerClass} = await importModule();
 
-  expect(
-    module.elementSelectorModalClass('CraftCms\\Cms\\Asset\\Elements\\Asset')
-  ).toBe(PluginAssetModal);
+  expect(elementSelectorControllerClass(ASSET)).toBe(PluginAssetController);
 });
diff --git a/resources/js/modules/element-selector-modal/index.ts b/resources/js/modules/element-selector-modal/index.ts
index be4d32f58d4..331163647a3 100644
--- a/resources/js/modules/element-selector-modal/index.ts
+++ b/resources/js/modules/element-selector-modal/index.ts
@@ -1,58 +1,51 @@
 import {registerCraftGlobals} from '@/common/craft-global';
 import {
   AssetSelectorController,
-  adoptLegacyRegistrations as adoptLegacyControllerRegistrations,
+  ElementSelectorController,
+  adoptLegacyRegistrations,
   hasElementSelectorController,
   registerElementSelectorController,
-  t,
 } from '@craftcms/ui';
-import {createElementSelectorModal as createModal} from './create-element-selector-modal';
-import {BaseElementSelectorModal} from './base-element-selector-modal';
-import {AssetSelectorModal} from './asset-selector-modal';
+import {createElementSelectorModal} from './create-element-selector-modal';
 import {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
-import {
-  adoptLegacyRegistrations,
-  createElementSelectorModal,
-  hasElementSelectorModalClass,
-  registerElementSelectorModalClass,
-} from './registry';
 
 const ASSET = 'CraftCms\\Cms\\Asset\\Elements\\Asset';
 
-BaseElementSelectorModal.defaults.modalTitle ??= t('Select element');
-BaseElementSelectorModal.defaults.selectBtnLabel ??= t('Select');
-
+// The legacy bundle is a plain `<script>` and runs before this module, so a
+// plugin can have registered a class before there was anywhere modern to put it.
 adoptLegacyRegistrations();
-adoptLegacyControllerRegistrations();
 
-// Skipped when something got there first, so a plugin can replace the built-in
-// asset modal without the duplicate-registration throw.
-if (!hasElementSelectorModalClass(ASSET)) {
-  registerElementSelectorModalClass(ASSET, AssetSelectorModal);
-}
-
-// Assets get transform support on the modern path. Same yield-to-a-plugin rule.
+// Assets get transform support. Skipped when something got there first, so a
+// plugin can replace the built-in behavior without the duplicate-registration
+// throw.
 if (!hasElementSelectorController(ASSET)) {
   registerElementSelectorController(ASSET, AssetSelectorController);
 }
 
-// The classes stay on `Craft` for PHP-emitted boots (`new
-// Craft.VolumeFolderSelectorModal(…)`); the registry functions stay for plugins.
+/**
+ * `Craft.*` stays the entry point for plugins and PHP-emitted boots
+ * (`new Craft.VolumeFolderSelectorModal(…)` in `MoveAssets.php` and the legacy
+ * `AssetIndex`).
+ *
+ * `createElementSelectorModal` is now **async** and resolves to a
+ * controller-backed handle rather than a modal object — a deliberate break, as
+ * the modal is no longer a class anyone can subclass. `registerElementSelectorController`
+ * replaces `registerElementSelectorModalClass`; plugins register a controller
+ * (business logic) and get both presentation layers for free.
+ */
 registerCraftGlobals({
-  BaseElementSelectorModal,
-  AssetSelectorModal,
   VolumeFolderSelectorModal,
-  // The modern factory: async, and returns a controller-backed handle.
-  createElementSelectorModal: createModal,
-  registerElementSelectorModalClass,
+  createElementSelectorModal,
+  registerElementSelectorController,
+  ElementSelectorController,
+  AssetSelectorController,
 });
 
-export {BaseElementSelectorModal} from './base-element-selector-modal';
-export {AssetSelectorModal} from './asset-selector-modal';
+export {createElementSelectorModal} from './create-element-selector-modal';
+export type {
+  ElementSelectorModalHandle,
+  ElementSelectorModalSettings,
+} from './create-element-selector-modal';
 export {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
-export {
-  createElementSelectorModal,
-  elementSelectorModalClass,
-  registerElementSelectorModalClass,
-  type ElementSelectorModalClass,
-} from './registry';
+export {default as ElementSelectorModal} from './ElementSelectorModal.vue';
+export {useElementSelectorController} from './useElementSelectorController';
diff --git a/resources/js/modules/element-selector-modal/registry.test.ts b/resources/js/modules/element-selector-modal/registry.test.ts
deleted file mode 100644
index 5c662ec645f..00000000000
--- a/resources/js/modules/element-selector-modal/registry.test.ts
+++ /dev/null
@@ -1,75 +0,0 @@
-import {afterEach, beforeEach, expect, it, vi} from 'vite-plus/test';
-import {BaseElementSelectorModal} from './base-element-selector-modal';
-import {
-  adoptLegacyRegistrations,
-  createElementSelectorModal,
-  elementSelectorModalClass,
-  hasElementSelectorModalClass,
-  registerElementSelectorModalClass,
-  resetElementSelectorModalClasses,
-} from './registry';
-
-class FakeModal {
-  constructor(
-    public elementType: string,
-    public settings?: Record<string, any>
-  ) {}
-}
-
-const ENTRY = 'CraftCms\\Cms\\Entry\\Elements\\Entry';
-
-beforeEach(() => resetElementSelectorModalClasses());
-
-afterEach(() => {
-  resetElementSelectorModalClasses();
-  vi.unstubAllGlobals();
-});
-
-it('falls back to the base modal for an unregistered element type', () => {
-  expect(elementSelectorModalClass(ENTRY)).toBe(BaseElementSelectorModal);
-  expect(hasElementSelectorModalClass(ENTRY)).toBe(false);
-});
-
-it('constructs the registered class with the element type and settings', () => {
-  registerElementSelectorModalClass(ENTRY, FakeModal as never);
-
-  const modal = createElementSelectorModal(ENTRY, {modalTitle: 'Choose'});
-
-  expect(modal).toBeInstanceOf(FakeModal);
-  expect((modal as unknown as FakeModal).elementType).toBe(ENTRY);
-  expect((modal as unknown as FakeModal).settings).toEqual({
-    modalTitle: 'Choose',
-  });
-});
-
-it('refuses a second registration for one element type', () => {
-  registerElementSelectorModalClass(ENTRY, FakeModal as never);
-
-  expect(() =>
-    registerElementSelectorModalClass(ENTRY, FakeModal as never)
-  ).toThrow(/already been registered/);
-});
-
-it('adopts classes the legacy bundle registered before it loaded', () => {
-  vi.stubGlobal('Craft', {_elementSelectorModalClasses: {[ENTRY]: FakeModal}});
-
-  adoptLegacyRegistrations();
-
-  expect(elementSelectorModalClass(ENTRY)).toBe(FakeModal);
-});
-
-it('keeps its own registration when the legacy bundle claims the same type', () => {
-  class Newer {}
-  registerElementSelectorModalClass(ENTRY, Newer as never);
-  vi.stubGlobal('Craft', {_elementSelectorModalClasses: {[ENTRY]: FakeModal}});
-
-  adoptLegacyRegistrations();
-
-  expect(elementSelectorModalClass(ENTRY)).toBe(Newer);
-});
-
-it('tolerates the legacy registry being gone', () => {
-  vi.stubGlobal('Craft', {});
-
-  expect(() => adoptLegacyRegistrations()).not.toThrow();
-});
diff --git a/resources/js/modules/element-selector-modal/registry.ts b/resources/js/modules/element-selector-modal/registry.ts
deleted file mode 100644
index 7b340ae2014..00000000000
--- a/resources/js/modules/element-selector-modal/registry.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import {BaseElementSelectorModal} from './base-element-selector-modal';
-
-export type ElementSelectorModalClass = new (
-  elementType: string,
-  settings?: Record<string, any>
-) => BaseElementSelectorModal;
-
-const classes = new Map<string, ElementSelectorModalClass>();
-
-/**
- * Registers the modal class to use for an element type.
- *
- * Throws on a second registration for the same type, matching the legacy
- * registry — two plugins claiming one element type is a conflict to surface,
- * not to resolve by last-write-wins.
- */
-export function registerElementSelectorModalClass(
-  elementType: string,
-  modalClass: ElementSelectorModalClass
-): void {
-  if (classes.has(elementType)) {
-    throw new Error(
-      `An element selector modal class has already been registered for the element type “${elementType}”.`
-    );
-  }
-
-  classes.set(elementType, modalClass);
-}
-
-export function hasElementSelectorModalClass(elementType: string): boolean {
-  return classes.has(elementType);
-}
-
-/** The class registered for an element type, or the base modal. */
-export function elementSelectorModalClass(
-  elementType: string
-): ElementSelectorModalClass {
-  return classes.get(elementType) ?? BaseElementSelectorModal;
-}
-
-export function createElementSelectorModal(
-  elementType: string,
-  settings?: Record<string, any>
-): BaseElementSelectorModal {
-  return new (elementSelectorModalClass(elementType))(elementType, settings);
-}
-
-/**
- * Takes over anything already on the legacy `Craft._elementSelectorModalClasses`
- * object.
- *
- * The legacy bundle is a plain script and runs before this module, so a plugin
- * can have registered before there was anywhere modern to put it. Existing
- * entries win over nothing here — a type this module registers itself is left
- * alone.
- */
-export function adoptLegacyRegistrations(): void {
-  const legacy = (window as any).Craft?._elementSelectorModalClasses as
-    | Record<string, ElementSelectorModalClass>
-    | undefined;
-
-  if (!legacy) {
-    return;
-  }
-
-  for (const [elementType, modalClass] of Object.entries(legacy)) {
-    if (!classes.has(elementType)) {
-      classes.set(elementType, modalClass);
-    }
-  }
-}
-
-/** Test seam. */
-export function resetElementSelectorModalClasses(): void {
-  classes.clear();
-}
diff --git a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
index cecda338a8e..969ffee3fb2 100644
--- a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
@@ -1,164 +1,334 @@
-import {hasAttr} from '@craftcms/garnish';
-import {BaseElementSelectorModal} from './base-element-selector-modal';
+import {ESC_KEY, hasAttr} from '@craftcms/garnish';
+import {
+  VolumeFolderSelectorController,
+  type SourcePathSegment,
+  type VolumeFolderSelectorOptions,
+} from '@craftcms/ui';
+import type CraftElementSelectorModal from '@craftcms/ui/components/element-selector-modal/element-selector-modal';
+import '@craftcms/ui/components/element-selector-modal/element-selector-modal';
+import {uiLayerManager} from '@/modules/slideout/slideout';
 
+declare const Craft: any;
 declare const $: any;
 
-const DEFAULTS = {
-  disabledFolderIds: [] as number[],
-  indexSettings: {} as Record<string, any>,
-};
+/** Below this the index's sidebar collapses behind a toggle. */
+const NARROW_THRESHOLD = 550;
+
+export interface VolumeFolderSelectorModalSettings extends VolumeFolderSelectorOptions {
+  /** Legacy Garnish setting, accepted and ignored. */
+  closeOtherModals?: boolean;
+}
 
 /**
- * VolumeFolderSelectorModal — a port of `Craft.VolumeFolderSelectorModal` onto
- * {@link BaseElementSelectorModal}. Forces folder-only browsing of asset volumes
- * and allows selecting the currently open folder even when no element is
- * highlighted.
+ * The folder picker used by asset moves.
+ *
+ * The one selector still driving the **legacy jQuery element index** rather than
+ * the Vue one, because folder picking keys off that index's `sourcePath` — the
+ * breadcrumb of the folder you have navigated into, which is what "select the
+ * folder I'm looking at" means when no row is highlighted. It is the last thing
+ * keeping `ElementIndexHtml` and the HTML `element-indexes/*` endpoints alive.
+ *
+ * It is also the proof that the chrome works with no Vue at all: the same
+ * `<craft-element-selector-modal>` and the same controller the Vue modal uses,
+ * with server HTML slotted in instead of a component tree.
+ *
+ * Opened `non-modal` deliberately. `showModal()` puts a dialog in the top layer,
+ * where it paints above every menu the legacy CP appends to `<body>` — the
+ * breadcrumb, status and site menus this index depends on — and makes them
+ * unclickable.
+ *
+ * @example
+ * new Craft.VolumeFolderSelectorModal({
+ *   sources: ['volume:…'],
+ *   disabledFolderIds: [12],
+ *   onSelect: ([folder]) => move(folder.folderId),
+ * });
  */
-export class VolumeFolderSelectorModal extends BaseElementSelectorModal {
-  static override defaults =
-    DEFAULTS as typeof BaseElementSelectorModal.defaults & typeof DEFAULTS;
-
-  constructor(settings?: any) {
-    super('CraftCms\\Cms\\Asset\\Elements\\Asset');
-    if (new.target === VolumeFolderSelectorModal) {
-      this.init(settings);
-    }
-  }
+export class VolumeFolderSelectorModal {
+  readonly controller: VolumeFolderSelectorController;
+  readonly element: CraftElementSelectorModal;
+
+  /** The legacy jQuery index, once booted. */
+  elementIndex: any = null;
+
+  #booted = false;
+  #resizeObserver: ResizeObserver | null = null;
+  #offChange: (() => void) | null = null;
+
+  // Narrow-viewport sidebar chrome, built lazily.
+  #$sidebar: any = null;
+  #$main: any = null;
+  #$content: any = null;
+  #$sidebarHeader: any = null;
+  #$mainHeader: any = null;
+  #$sidebarToggleBtn: any = null;
+  #$mainHeading: any = null;
+
+  constructor(settings: VolumeFolderSelectorModalSettings = {}) {
+    const {closeOtherModals: _ignored, ...options} = settings;
+
+    this.controller = new VolumeFolderSelectorController(options);
 
-  override init(settings?: any): void {
-    const merged = Object.assign(
-      {},
-      VolumeFolderSelectorModal.defaults,
-      settings,
-      {
-        // showSiteMenu is always false for folder selection
-        showSiteMenu: false,
+    this.element = document.createElement(
+      'craft-element-selector-modal'
+    ) as CraftElementSelectorModal;
+    this.element.controller = this.controller;
+    this.element.nonModal = true;
+    this.element.classList.add('elementselectormodal');
+    document.body.append(this.element);
+
+    this.#offChange = this.controller.on('change', (state) => {
+      if (state.indexBody) {
+        this.#bootIndex(state.indexBody.html);
       }
-    );
-    merged.indexSettings = Object.assign({}, merged.indexSettings, {
-      disabledFolderIds: merged.disabledFolderIds,
     });
-    super.init('CraftCms\\Cms\\Asset\\Elements\\Asset', merged);
+
+    this.controller.on('close', () => this.#closeSidebar());
+
+    void this.controller.open();
   }
 
-  /** The legacy jQuery index — see `_createElementIndex()` below. */
-  elementIndex: any = null;
+  show(): Promise<void> {
+    return this.controller.open();
+  }
+
+  hide(): void {
+    this.controller.close();
+  }
+
+  destroy(): void {
+    this.#offChange?.();
+    this.#offChange = null;
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
+    this.controller.destroy();
+    this.element.remove();
+  }
 
   /**
-   * Keeps the legacy element index, unlike every other selector modal.
+   * Boots the legacy index into the modal's default slot, once.
    *
-   * Folder picking is driven by the index's `sourcePath` — the breadcrumb of the
-   * folder you've navigated into, which is what "select the current folder"
-   * means when nothing is highlighted. The Vue index has no equivalent yet, so
-   * porting this one would lose that. It's the last thing keeping
-   * `ElementIndexHtml` and the HTML `element-indexes/*` endpoints alive.
+   * The HTML goes into light DOM rather than the component's shadow root, so the
+   * CP stylesheet — which this markup depends on entirely — still reaches it.
    */
-  override _createElementIndex(): void {
-    Craft.sendActionRequest('POST', this.settings.bodyAction, {
-      data: this.getElementIndexParams(),
-    }).then((response: any) => {
-      this.$body.html(response.data.html);
-
-      if (this.$body.has('.sidebar:not(.hidden)').length) {
-        this.$body.addClass('has-sidebar');
-        this.supportSidebarToggleView = true;
-      }
+  #bootIndex(html: string): void {
+    if (this.#booted) {
+      return;
+    }
+
+    this.#booted = true;
+    this.element.innerHTML = html;
 
-      this.elementIndex = (Craft as any).createElementIndex(
-        this.elementType,
-        this.$body.children('.element-index'),
-        this.getIndexSettings()
-      );
-
-      this.$main = this.elementIndex.$main;
-      this.$sidebar = this.elementIndex.$sidebar;
-      this.$content = this.$body.find('.content');
-
-      this.updateSidebarView();
-      this.updateModalBottomPadding();
-
-      $(this.elementIndex.$elements).on(
-        'doubletap',
-        (ev: any, touchData: any) => {
-          if (touchData.firstTap.target === touchData.secondTap.target) {
-            this.selectElements();
-          }
+    const $body = $(this.element);
+    this.elementIndex = Craft.createElementIndex(
+      this.controller.elementType,
+      $body.children('.element-index'),
+      this.#indexSettings()
+    );
+
+    this.#$main = this.elementIndex.$main;
+    this.#$sidebar = this.elementIndex.$sidebar;
+    this.#$content = $body.find('.content');
+
+    // `sourcePath` is read live, not captured: the controller consults it on
+    // every `canSubmit` evaluation, and it changes as the user navigates. The
+    // getter delegates to an arrow so it closes over this modal rather than the
+    // object literal it sits on.
+    const sourcePath = (): readonly SourcePathSegment[] =>
+      (this.elementIndex?.sourcePath ?? []) as SourcePathSegment[];
+
+    this.controller.attachIndex({
+      clearSelection: () => this.elementIndex?.clearSelection?.(),
+      get sourcePath(): readonly SourcePathSegment[] {
+        return sourcePath();
+      },
+      destroy: () => this.elementIndex?.destroy?.(),
+    });
+
+    // Double-click chooses. Kept on jQuery: `doubletap` is a jQuery-synthetic
+    // event, so `addEventListener` would never see it.
+    $(this.elementIndex.$elements).on(
+      'doubletap',
+      (_ev: any, touchData: any) => {
+        if (touchData.firstTap.target === touchData.secondTap.target) {
+          void this.controller.submit();
         }
-      );
+      }
+    );
 
-      this.on('updateSizeAndPosition', () => {
-        this.elementIndex.handleResize();
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObserver = new ResizeObserver(() => {
+        this.elementIndex?.handleResize?.();
+        this.#updateSidebarView();
       });
+      this.#resizeObserver.observe(this.element);
+    }
 
-      this.updateSelectBtnState();
-    });
+    this.#updateSidebarView();
   }
 
-  override hasSelection(): boolean {
-    return !!this.elementIndex?.getSelectedElements().length;
+  /**
+   * The index's own configuration.
+   *
+   * The controller supplies the query half; the callbacks are the binder's,
+   * because they are what pushes the legacy index's state into the controller.
+   */
+  #indexSettings(): Record<string, unknown> {
+    const pushSelection = () => {
+      const selected = this.elementIndex?.getSelectedElements?.() ?? [];
+      const elements = [];
+
+      for (let i = 0; i < selected.length; i++) {
+        const $element = $(selected.eq(i).find('.element:first'));
+        const folderId = parseInt($element.data('folder-id'), 10);
+
+        elements.push({
+          id: folderId,
+          folderId,
+          siteId: null,
+          label: String($element.data('label') ?? ''),
+          status: null,
+          url: null,
+          hasThumb: false,
+        });
+      }
+
+      this.controller.setSelection(elements as any);
+    };
+
+    return {
+      ...this.controller.indexSettings(),
+      buttonContainer: this.element.querySelector('[slot="secondary-actions"]'),
+      onSelectionChange: pushSelection,
+      // The current folder counts as a selection candidate, so a breadcrumb
+      // change has to re-run the controller's rules too.
+      onSourcePathChange: pushSelection,
+      onSelectSource: () => this.#updateHeading(),
+      viewSettings: () => ({
+        canSelectElement: ($element: any) =>
+          hasAttr($element.find('.element:first')[0], 'data-folder-id'),
+      }),
+    };
   }
 
-  override getElementIndexParams(): Record<string, any> {
-    return Object.assign({}, super.getElementIndexParams(), {
-      foldersOnly: true,
-    });
+  // ───────────────────── narrow-viewport sidebar ─────────────────────
+
+  get #supportsSidebarToggle(): boolean {
+    return !!this.#$sidebar?.length && !this.#$sidebar.hasClass('hidden');
   }
 
-  override shouldEnableSelectBtn(): boolean {
-    if (super.shouldEnableSelectBtn()) return true;
+  get #sidebarShouldBeHidden(): boolean {
+    return this.element.getBoundingClientRect().width < NARROW_THRESHOLD;
+  }
 
-    // Allow selecting the current folder when nothing is highlighted, unless
-    // it is in the disabled list.
-    const sourcePath = this.elementIndex?.sourcePath;
-    if (!sourcePath?.length) return false;
+  #updateSidebarView(): void {
+    if (!this.#supportsSidebarToggle) {
+      return;
+    }
 
-    const last = sourcePath[sourcePath.length - 1];
-    return (
-      typeof last.folderId !== 'undefined' &&
-      !this.settings.disabledFolderIds.includes(last.folderId)
-    );
+    if (this.#sidebarShouldBeHidden) {
+      this.#buildSidebarToggleView();
+    } else if (this.#$sidebarToggleBtn) {
+      this.#resetSidebarView();
+    }
   }
 
-  override selectElements(ev?: MouseEvent): void {
-    if (this.hasSelection()) {
-      super.selectElements();
+  #buildSidebarToggleView(): void {
+    if (this.#$sidebarToggleBtn) {
       return;
     }
 
-    if (
-      this.$selectBtn &&
-      ev?.currentTarget === this.$selectBtn[0] &&
-      this.shouldEnableSelectBtn()
-    ) {
-      const sourcePath = this.elementIndex.sourcePath;
-      const {folderId} = sourcePath[sourcePath.length - 1];
-      this.onSelect([{folderId}]);
-
-      if (this.settings.hideOnSelect) {
-        this.hide();
-      }
+    // `btn-empty` without `btn` reproduces what the legacy chrome emitted: an
+    // icon-only button taking its appearance from `nav-close` / `nav-toggle`.
+    const sidebarHeader = document.createElement('div');
+    sidebarHeader.className = 'sidebar-header';
+    const closeBtn = document.createElement('button');
+    closeBtn.type = 'button';
+    closeBtn.className = 'nav-close close-btn btn-empty';
+    closeBtn.setAttribute('aria-label', Craft.t('app', 'Close'));
+    sidebarHeader.append(closeBtn);
+    this.#$sidebar[0].prepend(sidebarHeader);
+    this.#$sidebarHeader = $(sidebarHeader);
+
+    const mainHeader = document.createElement('div');
+    mainHeader.className = 'main-header';
+    const heading = document.createElement('h2');
+    heading.className = 'main-heading';
+    heading.textContent = this.#activeSourceName();
+    const toggleBtn = document.createElement('button');
+    toggleBtn.type = 'button';
+    toggleBtn.className = 'nav-toggle btn-empty';
+    toggleBtn.setAttribute('aria-expanded', 'false');
+    toggleBtn.setAttribute('aria-controls', 'modal-sidebar');
+    toggleBtn.setAttribute('aria-label', Craft.t('app', 'Show sidebar'));
+    mainHeader.append(heading, toggleBtn);
+    this.#$main[0].prepend(mainHeader);
+    this.#$mainHeader = $(mainHeader);
+    this.#$mainHeading = $(heading);
+    this.#$sidebarToggleBtn = $(toggleBtn);
+
+    this.#$sidebar.attr('id', 'modal-sidebar');
+    this.#closeSidebar();
+
+    toggleBtn.addEventListener('click', () => this.#toggleSidebar());
+    closeBtn.addEventListener('click', () => this.#toggleSidebar());
+  }
+
+  #resetSidebarView(): void {
+    this.#$mainHeader?.remove();
+    this.#$sidebarHeader?.remove();
+    this.#$sidebarToggleBtn = null;
+    this.#$sidebar.removeClass('hidden');
+    this.#$content?.addClass('has-sidebar');
+  }
+
+  #sidebarIsOpen(): boolean {
+    return this.#$sidebarToggleBtn?.attr('aria-expanded') === 'true';
+  }
+
+  #toggleSidebar(): void {
+    if (this.#sidebarIsOpen()) {
+      this.#closeSidebar();
+    } else {
+      this.#openSidebar();
     }
   }
 
-  override getElementInfo($selectedElements: any): Array<{folderId: number}> {
-    const info: Array<{folderId: number}> = [];
-    for (let i = 0; i < $selectedElements.length; i++) {
-      const $element = $($selectedElements.eq(i).find('.element:first'));
-      const folderId = parseInt($element.data('folder-id'));
-      info.push({folderId});
+  #openSidebar(): void {
+    this.#$content?.addClass('has-sidebar');
+    this.#$sidebar.removeClass('hidden');
+    this.#$sidebarToggleBtn.attr('aria-expanded', 'true');
+    this.#$sidebar.find(':focusable').first().focus();
+
+    uiLayerManager().addLayer(this.#$sidebar[0]);
+    uiLayerManager().registerShortcut(ESC_KEY, () => this.#closeSidebar());
+  }
+
+  #closeSidebar(): void {
+    if (!this.#$sidebarToggleBtn) {
+      return;
+    }
+
+    if (this.#sidebarIsOpen()) {
+      uiLayerManager().removeLayer();
     }
-    return info;
+
+    this.#$sidebar.addClass('hidden');
+    this.#$sidebarToggleBtn.attr('aria-expanded', 'false');
+
+    const focused = document.activeElement;
+    if (focused && this.#$sidebar[0].contains(focused)) {
+      this.#$sidebarToggleBtn.focus();
+    }
+
+    this.#$content?.removeClass('has-sidebar');
   }
 
-  override getIndexSettings(): Record<string, any> {
-    return Object.assign(super.getIndexSettings(), {
-      foldersOnly: true,
-      viewSettings: () => ({
-        canSelectElement: ($element: any) => {
-          const inner = $element.find('.element:first');
-          return hasAttr(inner[0], 'data-folder-id');
-        },
-      }),
-    });
+  #activeSourceName(): string {
+    return this.#$sidebar?.find('.sel').text() ?? '';
+  }
+
+  #updateHeading(): void {
+    this.#$mainHeading?.text(this.#activeSourceName());
   }
 }

From 6e769039819a07807c29ac70122fdad994a2fdf4 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 08:28:33 -0500
Subject: [PATCH 23/24] Update the element selector modal README

---
 .../modules/element-selector-modal/README.md  | 52 ++++++++++++-------
 1 file changed, 33 insertions(+), 19 deletions(-)

diff --git a/resources/js/modules/element-selector-modal/README.md b/resources/js/modules/element-selector-modal/README.md
index c13ed5c992a..46ecb2a68d1 100644
--- a/resources/js/modules/element-selector-modal/README.md
+++ b/resources/js/modules/element-selector-modal/README.md
@@ -1,7 +1,6 @@
 # element-selector-modal
 
-The Vue presentation layer for the element selector, plus what is left of the
-legacy modal it replaced.
+The Vue presentation layer for the element selector.
 
 The business logic does **not** live here — it lives in
 `@craftcms/ui`'s [`core/element-selector`](../../../../packages/craftcms-ui/src/core/element-selector/),
@@ -44,8 +43,7 @@ index reusable and `useModalElementIndex` core-agnostic.
 | `useModalElementIndex.ts` | The composable behind it — the page's own `useElementIndex*` stack with a non-Inertia visitor. |
 | `modal-index-visitor.ts` | That visitor. |
 | `index.ts` | Registers the asset controller, drains legacy registrations, assigns the `Craft.*` shims. |
-| `volume-folder-selector-modal.ts` | **Still on the legacy modal.** See below. |
-| `base-element-selector-modal.ts`, `asset-selector-modal.ts`, `registry.ts` | **Legacy.** Only the volume-folder modal still reaches them. |
+| `volume-folder-selector-modal.ts` | The folder picker. Binds the same web component and controller to the **legacy jQuery index** — no Vue at all. |
 
 ## What the payload looks like
 
@@ -59,21 +57,37 @@ let a column silently overwrite anything sharing its name — `status` came back
 a `<craft-badge>` element rather than `"pending"`, and `kind` would have come back
 as `"Image"` rather than `"image"` whenever the File Kind column was visible.
 
-## The legacy remnant
-
-`volume-folder-selector-modal.ts` still extends `BaseElementSelectorModal`,
-because it drives the **legacy jQuery element index** rather than the Vue one:
-folder picking keys off the index's `sourcePath` (the breadcrumb of the folder
-you have navigated into), which is what "select the folder I'm looking at" means
-when no row is highlighted. It is the last thing keeping `ElementIndexHtml` and
-the HTML `element-indexes/*` endpoints alive.
-
-`VolumeFolderSelectorController` is already written and tested in the core, and
-`<craft-element-selector-modal>` has a `non-modal` mode for exactly this case —
-a top-layer dialog paints above `<body>`-appended menus, which is most of the
-legacy CP. What remains is the binder: create the element, slot
-`response.data.html` into it, boot `Craft.createElementIndex`, and adapt it to
-`VolumeFolderIndexAdapter`. Deleting the three legacy files falls out of that.
+## The folder picker
+
+`volume-folder-selector-modal.ts` drives the **legacy jQuery element index**
+rather than the Vue one, because folder picking keys off that index's
+`sourcePath` — the breadcrumb of the folder you have navigated into, which is
+what "select the folder I'm looking at" means when no row is highlighted. It is
+the last thing keeping `ElementIndexHtml` and the HTML `element-indexes/*`
+endpoints alive.
+
+It is also the proof that this split works: the same web component and the same
+controller as the Vue modal, with server HTML slotted in instead of a component
+tree, and a `VolumeFolderIndexAdapter` bridging the jQuery index to the core.
+
+It opens **`non-modal`** deliberately. `showModal()` puts a dialog in the top
+layer, where it paints above every menu the legacy CP appends to `<body>` — the
+breadcrumb, status and site menus this index depends on — and makes them
+unclickable. `show()` keeps it in the normal stacking context; the component
+supplies the backdrop, Escape and focus containment the platform then stops
+providing.
+
+The day a Vue folder index exists, this file collapses into
+`ElementSelectorModal.vue`.
+
+### A rule this fixed
+
+"Select the folder I'm looking at" never actually worked. The legacy modal gated
+it on `ev.currentTarget === this.$selectBtn[0]`, but the base class bound the
+click as a zero-argument arrow, so `ev` was always `undefined`: the Select button
+would enable and then do nothing. The rule now lives in the controller's
+`canSubmitSelection()` and `buildElementInfo()`, so the inherited `submit()`
+handles both cases with no override and no event to inspect.
 
 ## Registry
 

From 4490d837e470e21302bc918a1564e13f24fcc1cd Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Sat, 22 Aug 2026 10:06:44 -0500
Subject: [PATCH 24/24] Cover the folder picker binder and fix its folder id
 lookup

---
 .../modules/element-selector-modal/index.ts   |   8 +-
 .../volume-folder-selector-modal.test.ts      | 227 ++++++++++++++++++
 .../volume-folder-selector-modal.ts           |   7 +-
 3 files changed, 238 insertions(+), 4 deletions(-)
 create mode 100644 resources/js/modules/element-selector-modal/volume-folder-selector-modal.test.ts

diff --git a/resources/js/modules/element-selector-modal/index.ts b/resources/js/modules/element-selector-modal/index.ts
index 331163647a3..fdb15e8c463 100644
--- a/resources/js/modules/element-selector-modal/index.ts
+++ b/resources/js/modules/element-selector-modal/index.ts
@@ -47,5 +47,9 @@ export type {
   ElementSelectorModalSettings,
 } from './create-element-selector-modal';
 export {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
-export {default as ElementSelectorModal} from './ElementSelectorModal.vue';
-export {useElementSelectorController} from './useElementSelectorController';
+
+// `ElementSelectorModal.vue` and `useElementSelectorController` are deliberately
+// NOT re-exported here. `cp.ts` imports this module for its side effects, and a
+// static re-export would pull the Vue view — and with it the whole element-index
+// component tree — into every CP page, which is exactly what the factory's lazy
+// `import()` exists to avoid. Import them from their own modules.
diff --git a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.test.ts b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.test.ts
new file mode 100644
index 00000000000..486834b1f00
--- /dev/null
+++ b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.test.ts
@@ -0,0 +1,227 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+import $ from 'jquery';
+import {VolumeFolderSelectorModal} from './volume-folder-selector-modal';
+
+if (typeof HTMLDialogElement !== 'undefined') {
+  HTMLDialogElement.prototype.showModal ??= function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.show ??= function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.close ??= function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  };
+}
+
+const INDEX_HTML = `
+  <div class="element-index">
+    <div class="sidebar"><a class="sel">Volume A</a></div>
+    <div class="main"><div class="content"><table><tbody></tbody></table></div></div>
+  </div>
+`;
+
+/** Stands in for the legacy jQuery index the binder boots. */
+function fakeIndex(sourcePath: {folderId?: number; label?: string}[] = []) {
+  const selected: {folderId: number; label: string}[] = [];
+
+  return {
+    sourcePath,
+    selected,
+    $main: $('<div class="main"></div>'),
+    $sidebar: $('<div class="sidebar"><a class="sel">Volume A</a></div>'),
+    $elements: $('<div></div>'),
+    clearSelection: vi.fn(),
+    handleResize: vi.fn(),
+    destroy: vi.fn(),
+    getSelectedElements() {
+      // The legacy index hands back a jQuery collection of row wrappers, each
+      // containing an `.element` carrying the folder id.
+      const rows = selected.map(
+        (f) =>
+          $(
+            `<div><div class="element" data-folder-id="${f.folderId}" data-label="${f.label}"></div></div>`
+          )[0]
+      );
+      return $(rows);
+    },
+  };
+}
+
+let index: ReturnType<typeof fakeIndex>;
+let createElementIndex: ReturnType<typeof vi.fn>;
+
+function createModal(settings: Record<string, unknown> = {}) {
+  return new VolumeFolderSelectorModal({
+    loadIndexBody: async () => ({html: INDEX_HTML, props: {}}),
+    ...settings,
+  } as any);
+}
+
+/** The binder boots the index from a `change` event, so give it a few ticks. */
+async function settle(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 0));
+  }
+}
+
+beforeEach(() => {
+  index = fakeIndex();
+  createElementIndex = vi.fn(() => index);
+  vi.stubGlobal('$', $);
+  vi.stubGlobal('Craft', {
+    t: (_category: string, message: string) => message,
+    createElementIndex,
+  });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.body.replaceChildren();
+});
+
+describe('chrome', () => {
+  it('opens out of the top layer', async () => {
+    // `showModal()` would paint above the `<body>`-appended menus this index
+    // depends on.
+    const modal = createModal();
+    await settle();
+
+    expect(document.body.contains(modal.element)).toBe(true);
+    expect(modal.element.nonModal).toBe(true);
+    modal.destroy();
+  });
+
+  it('takes its copy from the settings', async () => {
+    const modal = createModal({
+      showTitle: true,
+      modalTitle: 'Move to',
+      selectBtnLabel: 'Move',
+    });
+    await settle();
+
+    const shadow = modal.element.shadowRoot!;
+    expect(shadow.querySelector('[part="title"]')!.textContent!.trim()).toBe(
+      'Move to'
+    );
+    expect(shadow.querySelector('[part="select"]')!.textContent!.trim()).toBe(
+      'Move'
+    );
+    modal.destroy();
+  });
+});
+
+describe('booting the legacy index', () => {
+  it('slots the server HTML into light DOM so the CP stylesheet reaches it', async () => {
+    const modal = createModal();
+    await settle();
+
+    expect(modal.element.querySelector('.element-index')).not.toBeNull();
+    modal.destroy();
+  });
+
+  it('boots the index once, with folders-only settings', async () => {
+    const modal = createModal({disabledFolderIds: [7]});
+    await settle();
+    await modal.controller.reload();
+    await settle();
+
+    expect(createElementIndex).toHaveBeenCalledTimes(1);
+    const [elementType, , settings] = createElementIndex.mock.calls[0]!;
+    expect(elementType).toBe('CraftCms\\Cms\\Asset\\Elements\\Asset');
+    expect(settings).toMatchObject({
+      foldersOnly: true,
+      disabledFolderIds: [7],
+      context: 'modal',
+    });
+    modal.destroy();
+  });
+
+  it('asks the server for folders only', async () => {
+    const modal = createModal();
+    await settle();
+
+    expect(modal.controller.indexParams()).toMatchObject({
+      foldersOnly: true,
+      // Folders don't vary by site.
+      showSiteMenu: '0',
+    });
+    modal.destroy();
+  });
+});
+
+describe('selection', () => {
+  it('pushes highlighted folders into the controller', async () => {
+    const modal = createModal();
+    await settle();
+
+    index.selected.push({folderId: 12, label: 'Nested'});
+    const settings = createElementIndex.mock.calls[0]![2] as any;
+    settings.onSelectionChange();
+
+    expect(modal.controller.state.selection).toHaveLength(1);
+    expect(modal.controller.state.selection[0]!.folderId).toBe(12);
+    expect(modal.controller.state.canSubmit).toBe(true);
+    modal.destroy();
+  });
+
+  it('hands the highlighted folder to onSelect', async () => {
+    const onSelect = vi.fn();
+    const modal = createModal({onSelect, hideOnSelect: false});
+    await settle();
+
+    index.selected.push({folderId: 12, label: 'Nested'});
+    (createElementIndex.mock.calls[0]![2] as any).onSelectionChange();
+    await modal.controller.submit();
+
+    expect(onSelect.mock.calls[0]![0][0]).toMatchObject({folderId: 12});
+    modal.destroy();
+  });
+
+  it('reads the breadcrumb live, so the open folder is selectable', async () => {
+    // This is the rule that never worked in the legacy modal: it gated on an
+    // event target that was always undefined.
+    const onSelect = vi.fn();
+    const modal = createModal({onSelect, hideOnSelect: false});
+    await settle();
+
+    expect(modal.controller.state.canSubmit).toBe(false);
+
+    index.sourcePath.push({folderId: 1, label: 'Volume'});
+    index.sourcePath.push({folderId: 9, label: 'Open folder'});
+    // Navigating re-runs the rules; that is what `onSourcePathChange` is for.
+    (createElementIndex.mock.calls[0]![2] as any).onSourcePathChange();
+
+    expect(modal.controller.state.canSubmit).toBe(true);
+    await modal.controller.submit();
+
+    expect(onSelect.mock.calls[0]![0][0]).toMatchObject({
+      folderId: 9,
+      label: 'Open folder',
+    });
+    modal.destroy();
+  });
+
+  it('refuses an open folder that is disabled', async () => {
+    const modal = createModal({disabledFolderIds: [9]});
+    await settle();
+    index.sourcePath.push({folderId: 9});
+    (createElementIndex.mock.calls[0]![2] as any).onSourcePathChange();
+
+    expect(modal.controller.state.canSubmit).toBe(false);
+    modal.destroy();
+  });
+});
+
+describe('teardown', () => {
+  it('destroys the index and removes the element', async () => {
+    const modal = createModal();
+    await settle();
+
+    modal.destroy();
+
+    expect(index.destroy).toHaveBeenCalled();
+    expect(document.body.contains(modal.element)).toBe(false);
+  });
+});
diff --git a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
index 969ffee3fb2..ec4f9477772 100644
--- a/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
+++ b/resources/js/modules/element-selector-modal/volume-folder-selector-modal.ts
@@ -179,7 +179,10 @@ export class VolumeFolderSelectorModal {
       const elements = [];
 
       for (let i = 0; i < selected.length; i++) {
-        const $element = $(selected.eq(i).find('.element:first'));
+        // `.first()`, not the deprecated `:first` positional selector — jQuery's
+        // engine does not resolve that one here and silently matches nothing,
+        // which turned every folder id into NaN.
+        const $element = selected.eq(i).find('.element').first();
         const folderId = parseInt($element.data('folder-id'), 10);
 
         elements.push({
@@ -206,7 +209,7 @@ export class VolumeFolderSelectorModal {
       onSelectSource: () => this.#updateHeading(),
       viewSettings: () => ({
         canSelectElement: ($element: any) =>
-          hasAttr($element.find('.element:first')[0], 'data-folder-id'),
+          hasAttr($element.find('.element').first()[0], 'data-folder-id'),
       }),
     };
   }