From f1a67cba613f5c5980118e59b9e53f1c6280f8bf Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 11:23:34 -0500
Subject: [PATCH 01/15] Port Craft.NestedElementManager to a modern module

Moves the legacy jQuery NestedElementManager into
resources/js/modules/nested-element-manager/ following the shared module
pattern: a logic class on @craftcms/garnish Base (modern Select/DragSort
for card selection and drag-sorting, documented jQuery seams for the
Craft.ui buttons, disclosure/expandable menus, element index, editor
slideouts, and Craft.cp), a <craft-nested-element-manager>
ControllerElement that boots from an element-type attribute and a JSON
settings attribute, a WeakMap instance registry, and an index shim that
assigns window.Craft.NestedElementManager (the constructor still accepts
the legacy three-argument signature for plugin boots).

NestedElementManager::createView() now emits the custom element around
its rendered markup instead of an HtmlStack JS boot, so the manager
self-boots and re-boots across Inertia fragment swaps. destroy() now
actually tears down listeners and the Select/DragSort instances.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/craftcms-legacy/cp/src/Craft.js      |    1 -
 .../cp/src/js/NestedElementManager.js         | 1220 --------------
 resources/js/cp.ts                            |    1 +
 resources/js/legacy.ts                        |    1 +
 .../modules/nested-element-manager/README.md  |   62 +
 .../modules/nested-element-manager/index.ts   |   26 +
 .../nested-element-manager.ce.ts              |   50 +
 .../nested-element-manager.ts                 | 1419 +++++++++++++++++
 .../modules/nested-element-manager/support.ts |   14 +
 src/Element/NestedElementManager.php          |   19 +-
 10 files changed, 1580 insertions(+), 1233 deletions(-)
 delete mode 100644 packages/craftcms-legacy/cp/src/js/NestedElementManager.js
 create mode 100644 resources/js/modules/nested-element-manager/README.md
 create mode 100644 resources/js/modules/nested-element-manager/index.ts
 create mode 100644 resources/js/modules/nested-element-manager/nested-element-manager.ce.ts
 create mode 100644 resources/js/modules/nested-element-manager/nested-element-manager.ts
 create mode 100644 resources/js/modules/nested-element-manager/support.ts

diff --git a/packages/craftcms-legacy/cp/src/Craft.js b/packages/craftcms-legacy/cp/src/Craft.js
index 622c9f7b839..cfc2f150510 100644
--- a/packages/craftcms-legacy/cp/src/Craft.js
+++ b/packages/craftcms-legacy/cp/src/Craft.js
@@ -73,7 +73,6 @@ import './js/LightSwitch.js';
 import './js/LinkField.js';
 import './js/LinkInput.js';
 import './js/LivePreview.js';
-import './js/NestedElementManager.js';
 import './js/PasswordInput.js';
 import './js/Preview.js';
 import './js/PreviewFileModal.js';
diff --git a/packages/craftcms-legacy/cp/src/js/NestedElementManager.js b/packages/craftcms-legacy/cp/src/js/NestedElementManager.js
deleted file mode 100644
index c7e63ff0400..00000000000
--- a/packages/craftcms-legacy/cp/src/js/NestedElementManager.js
+++ /dev/null
@@ -1,1220 +0,0 @@
-/** global: Craft */
-
-/**
- * Nested element manager
- */
-Craft.NestedElementManager = Garnish.Base.extend(
-  {
-    $container: null,
-    $btnContainer: null,
-    elementType: null,
-    $createBtn: null,
-    $pasteBtn: null,
-
-    // cards
-    $elements: null,
-    elementSort: null,
-    elementSelect: null,
-
-    // index
-    elementIndex: null,
-
-    /**
-     * @type {Craft.ElementEditor|null}
-     */
-    elementEditor: null,
-    creatingElement: false,
-
-    init: function (container, elementType, settings) {
-      this.$container = $(container);
-      this.elementType = elementType;
-      this.setSettings(settings, Craft.NestedElementManager.defaults);
-
-      // Is this already a nested element manager?
-      if (this.$container.data('nestedElementManager')) {
-        console.warn(
-          'Double-instantiating a nested element manager on an element'
-        );
-        this.$container.data('nestedElementManager').destroy();
-      }
-
-      this.$container.data('nestedElementManager', this);
-
-      if (this.settings.mode === 'cards') {
-        if (this.$container.is(':has(.elements)')) {
-          this.initCards();
-        }
-      } else {
-        this.initElementIndex();
-      }
-
-      if (this.settings.canCreate) {
-        let $createBtn = Craft.ui
-          .createButton({
-            icon: 'plus',
-            label: this.settings.createButtonLabel,
-            spinner: true,
-          })
-          .addClass('icon disabled');
-
-        if (this.settings.mode === 'cards') {
-          $createBtn.addClass('dashed wrap');
-        }
-
-        this.addButton($createBtn);
-
-        if (Array.isArray(this.settings.createAttributes)) {
-          const createMenuId = `menu-${Math.floor(Math.random() * 1000000)}`;
-          $('<div/>', {
-            id: createMenuId,
-            class: 'menu menu--disclosure',
-            'data-with-search-input':
-              this.settings.createAttributes.length > 5 ? 'true' : null,
-          }).insertAfter($createBtn);
-          $createBtn
-            .attr('aria-controls', createMenuId)
-            .attr('data-disclosure-trigger', 'true')
-            .addClass('menubtn')
-            .disclosureMenu();
-          const disclosureMenu = $createBtn.data('disclosureMenu');
-
-          // can't use Object.groupBy() here because the group order matters
-          const groupedCreateAttributes = {};
-          const groupOrder = [];
-          this.settings.createAttributes.forEach((attributes) => {
-            const group = attributes.group || Craft.t('app', 'General');
-            if (!groupedCreateAttributes[group]) {
-              groupedCreateAttributes[group] = [];
-              groupOrder.push(group);
-            }
-            groupedCreateAttributes[group].push(attributes);
-          });
-          const multiGroup = groupOrder.length > 1;
-
-          groupOrder.forEach((group) => {
-            if (multiGroup) {
-              disclosureMenu.addHr();
-              disclosureMenu.addGroup(group, false);
-            }
-
-            groupedCreateAttributes[group].forEach((attributes) => {
-              disclosureMenu.addItem({
-                icon: attributes.icon ? $(attributes.icon)[0] : null,
-                label: attributes.label,
-                iconColor: attributes.color,
-                onActivate: async () => {
-                  $createBtn.addClass('loading');
-                  await this.createElement(attributes.attributes);
-                  $createBtn.removeClass('loading');
-                },
-              });
-            });
-          });
-
-          if (multiGroup && this.settings.mode === 'cards') {
-            const $collapsedContainer = $(
-              '<div class="expandable-button--collapsed"/>'
-            ).insertAfter($createBtn);
-            $collapsedContainer.append($createBtn);
-            const $expandedContainer = $(
-              '<div class="expandable-button--expanded btngroup hidden"/>'
-            ).insertAfter($collapsedContainer);
-
-            // Add a SR-only description for each disclosure button
-            const btngroupDescriptionId = `btngroup-desc-${Math.floor(
-              Math.random() * 100000
-            )}`;
-            const $btngroupDescription = $('<span>', {
-              id: btngroupDescriptionId,
-              hidden: true,
-              html: Craft.t('app', 'Create {type}', {
-                type:
-                  Craft.elementTypeNames[this.elementType][2] ??
-                  Craft.t('app', 'element'),
-              }),
-            });
-            $expandedContainer.append($btngroupDescription);
-
-            groupOrder.forEach((group, i) => {
-              const $groupCreateBtn = Craft.ui
-                .createButton({
-                  icon: i === 0 ? 'plus' : null,
-                  label: group,
-                  ariaDescribedBy: btngroupDescriptionId,
-                  spinner: true,
-                })
-                .addClass('icon disabled dashed')
-                .appendTo($expandedContainer);
-              const groupCreateMenuId = `menu-${Math.floor(
-                Math.random() * 1000000
-              )}`;
-              $('<div/>', {
-                id: groupCreateMenuId,
-                class: 'menu menu--disclosure',
-              }).appendTo($expandedContainer);
-              $groupCreateBtn
-                .attr('aria-controls', groupCreateMenuId)
-                .attr('data-disclosure-trigger', 'true')
-                .addClass('menubtn')
-                .disclosureMenu();
-              const groupDisclosureMenu =
-                $groupCreateBtn.data('disclosureMenu');
-
-              groupedCreateAttributes[group].forEach((attributes) => {
-                groupDisclosureMenu.addItem({
-                  icon: attributes.icon ? $(attributes.icon)[0] : null,
-                  label: attributes.label,
-                  iconColor: attributes.color,
-                  onActivate: async () => {
-                    $groupCreateBtn.addClass('loading');
-                    await this.createElement(attributes.attributes);
-                    $groupCreateBtn.removeClass('loading');
-                  },
-                });
-              });
-
-              $createBtn = $createBtn.add($groupCreateBtn);
-            });
-
-            $collapsedContainer.expandableButton();
-          }
-        } else {
-          this.addListener($createBtn, 'activate', async (ev) => {
-            ev.preventDefault();
-            $createBtn.addClass('loading');
-            await this.createElement(this.settings.createAttributes);
-            $createBtn.removeClass('loading');
-          });
-        }
-
-        this.$createBtn = $createBtn;
-
-        if (this.settings.mode === 'cards') {
-          this.updateCreateBtn();
-        }
-      }
-
-      setTimeout(() => {
-        this.elementEditor = this.$container
-          .closest('form')
-          .data('elementEditor');
-
-        if (this.elementEditor) {
-          this.elementEditor.on('update', () => {
-            this.settings.ownerId = this.elementEditor.getDraftElementId(
-              this.settings.ownerId
-            );
-
-            if (this.elementIndex) {
-              this.elementIndex.settings.criteria[this.settings.ownerIdParam] =
-                this.settings.ownerId;
-            }
-          });
-        }
-
-        this.trigger('afterInit');
-      }, 100);
-
-      Craft.cp.onCopyElements((elementInfo, buttonLabel) => {
-        this.updatePasteButton(elementInfo);
-        if (this.$pasteBtn && buttonLabel) {
-          this.$pasteBtn.find('.label').text(buttonLabel);
-        }
-      });
-    },
-
-    bulkActionMode: function ($element) {
-      return (
-        this.elementSelect?.totalSelected > 1 &&
-        this.elementSelect.isSelected($element)
-      );
-    },
-
-    addButton($button) {
-      if (this.settings.mode === 'cards') {
-        if (!this.$btnContainer) {
-          this.$btnContainer = $btnContainer = $('<div/>', {
-            class: 'flex flex-inline',
-          }).appendTo(this.$container);
-        }
-        $button.appendTo(this.$btnContainer);
-        this.updateCreateBtn();
-      } else {
-        $button.appendTo(this.elementIndex.$toolbar);
-      }
-    },
-
-    initCards() {
-      this.$elements = this.$container.children('.elements');
-
-      // Was .elements just created?
-      if (!this.$elements.length) {
-        this.$elements = $('<ul/>', {
-          class: `elements ${this.settings.showInGrid ? 'card-grid' : 'cards'}`,
-        }).prependTo(this.$container);
-        this.$container.children('.zilch').addClass('hidden');
-      }
-
-      if (this.settings.selectable) {
-        this.elementSelect = new Garnish.Select(
-          this.$elements,
-          this.$elements.children().children('.element'),
-          {
-            multi: true,
-            vertical: !this.settings.showInGrid,
-            filter: (target) => {
-              return !$(target).closest(
-                'a[href],.toggle,.btn,[role=button],.move,craft-copy-attribute'
-              ).length;
-            },
-            checkboxMode: true,
-            waitForDoubleClicks: true,
-          }
-        );
-      }
-
-      // only initialise drag-sorting if the device has mouse events
-      if (this.settings.sortable && Craft.hasMousePointerEvents()) {
-        this.elementSort = new Garnish.DragSort({
-          container: this.$elements,
-          filter: this.settings.selectable
-            ? () => {
-                // Only return all the selected items if the target item is selected
-                if (
-                  this.elementSort.$targetItem
-                    .children('.element')
-                    .hasClass('sel')
-                ) {
-                  return this.elementSelect.getSelectedItems().parent('li');
-                } else {
-                  return this.elementSort.$targetItem;
-                }
-              }
-            : null,
-          handle:
-            '> .element > .card-titlebar > .card-actions-container > .card-actions > .move-btn',
-          ignoreHandleSelector: null,
-          collapseDraggees: true,
-          magnetStrength: 4,
-          helperLagBase: 1.5,
-          onSortChange: () => {
-            this.onSortChange(this.elementSort.$draggee);
-          },
-        });
-      }
-
-      for (const element of this.$elements.children().toArray()) {
-        this.initElement($(element).children('.element'));
-      }
-    },
-
-    deinitCards() {
-      if (!this.$elements) {
-        return;
-      }
-
-      this.$elements.remove();
-      this.$elements = null;
-      this.elementSort?.destroy();
-      this.elementSort = null;
-      this.$container.children('.zilch').removeClass('hidden');
-    },
-
-    initElementIndex() {
-      this.elementIndex = Craft.createElementIndex(
-        this.elementType,
-        this.$container,
-        Object.assign(
-          {
-            context: 'embedded-index',
-            sortable: this.settings.sortable,
-            prevalidate: this.settings.prevalidate,
-          },
-          this.settings.indexSettings,
-          {
-            canDuplicateElements: ($selectedItems) => {
-              return this.canCreate($selectedItems.length);
-            },
-            canDeleteElements: ($selectedItems) => {
-              return this.canDelete($selectedItems.length);
-            },
-            onBeforeMoveElementsToPage: async () => {
-              await this.markAsDirty();
-            },
-            onMoveElementsToPage: async () => {
-              await this.markAsDirty();
-            },
-            onBeforeReorderElements: async () => {
-              await this.markAsDirty();
-            },
-            onReorderElements: async () => {
-              await this.markAsDirty();
-            },
-            onBeforeDuplicateElements: async () => {
-              await this.markAsDirty();
-            },
-            onDuplicateElements: async () => {
-              await this.markAsDirty();
-            },
-            onBeforeDeleteElements: async () => {
-              await this.markAsDirty();
-            },
-            onDeleteElements: async () => {
-              if (!(await this.markAsDirty())) {
-                // save the element anyway in case any conditional fields should be shown/hidden
-                this.elementEditor?.checkForm(true);
-              }
-            },
-            onBeforeUpdateElements: () => {
-              if (this.$createBtn) {
-                this.$createBtn.addClass('disabled');
-              }
-            },
-            onCountResults: () => {
-              this.updateCreateBtn();
-            },
-            onSortChange: async ($draggee) => {
-              await this.onSortChange($draggee);
-            },
-          }
-        )
-      );
-    },
-
-    async markAsDirty() {
-      if (!this.elementEditor || !this.settings.baseInputName) {
-        return false;
-      }
-      return await this.elementEditor.setFormValue(
-        this.settings.baseInputName,
-        '*'
-      );
-    },
-
-    async getBaseActionData() {
-      // this could end up updating this.settings.ownerId
-      await this.markAsDirty();
-
-      return {
-        ownerElementType: this.settings.ownerElementType,
-        ownerId: this.settings.ownerId,
-        ownerSiteId: this.settings.ownerSiteId,
-        attribute: this.settings.attribute,
-      };
-    },
-
-    async onSortChange($draggee) {
-      const elementIds = $draggee
-        .find('.element')
-        .toArray()
-        .map((element) => parseInt($(element).data('id')));
-
-      try {
-        const response = await this.updateSortOrder(elementIds);
-        Craft.cp.displayNotice(response.data.message);
-        if (Craft.broadcaster && this.elementEditor?.settings.draftId) {
-          Craft.broadcaster.postMessage({
-            pageId: Craft.pageId,
-            event: 'reorderNestedElements',
-            canonicalId: this.elementEditor.settings.canonicalId,
-            draftId: this.elementEditor.settings.draftId,
-            isProvisionalDraft: this.elementEditor.settings.isProvisionalDraft,
-            elementType: this.elementType,
-            elementIds,
-          });
-        }
-      } catch (e) {
-        Craft.cp.displayError(e?.response?.data?.message);
-      }
-
-      if (!(await this.markAsDirty())) {
-        // Refresh Live Preview
-        Craft.Preview.refresh();
-      }
-    },
-
-    async updateSortOrder(elementIds) {
-      elementIds = Array.isArray(elementIds) ? elementIds : [elementIds];
-      elementIds = elementIds.map((id) => parseInt(id));
-      const allIds = this.getElementIds();
-
-      const data = Object.assign(await this.getBaseActionData(), {
-        elementIds,
-        offset: this.getBaseElementOffset() + allIds.indexOf(elementIds[0]),
-      });
-
-      return await Craft.sendActionRequest('POST', 'nested-elements/reorder', {
-        data,
-      });
-    },
-
-    updateCreateBtn() {
-      if (!this.$createBtn) {
-        return;
-      }
-
-      if (this.canCreate()) {
-        this.$createBtn.removeClass('disabled');
-      } else {
-        this.$createBtn.addClass('disabled');
-      }
-
-      this.updatePasteButton();
-    },
-
-    updatePasteButton(elementInfo = null) {
-      elementInfo = elementInfo || Craft.cp.getCopiedElements();
-      if (this.canPaste(elementInfo)) {
-        if (!this.$pasteBtn) {
-          this.$pasteBtn = Craft.ui.createPasteButton();
-          this.addButton(this.$pasteBtn);
-          this.addListener(this.$pasteBtn, 'activate', 'pasteElements');
-        } else {
-          this.$pasteBtn.removeClass('hidden');
-        }
-      } else {
-        this.$pasteBtn?.addClass('hidden');
-      }
-    },
-
-    canCreate(num = 1) {
-      if (!this.settings.canCreate || num === 0) {
-        return false;
-      }
-
-      if (!this.settings.maxElements) {
-        return true;
-      }
-
-      const total = this.getTotalElements();
-
-      return total !== null && total + num <= this.settings.maxElements;
-    },
-
-    canDelete() {
-      if (!this.settings.minElements) {
-        return true;
-      }
-
-      return this.getTotalElements() !== null;
-    },
-
-    canPaste(elementInfo) {
-      if (!this.settings.canPaste || !this.canCreate(elementInfo.length)) {
-        return false;
-      }
-
-      for (const e of elementInfo) {
-        if (e.type !== this.elementType) {
-          return false;
-        }
-      }
-
-      if (typeof this.settings.canPaste === 'function') {
-        return this.settings.canPaste(elementInfo);
-      }
-
-      if (typeof this.settings.canPaste === 'string') {
-        return eval(this.settings.canPaste)(elementInfo);
-      }
-
-      return true;
-    },
-
-    getElementIds() {
-      let elements;
-
-      if (this.settings.mode === 'cards') {
-        elements = this.$elements.find('> li > .element').toArray();
-      } else {
-        elements = this.elementIndex.view
-          .getAllElements()
-          .toArray()
-          .map((container) => container.querySelector('.element'));
-      }
-
-      return elements
-        .map((element) => element.getAttribute('data-id'))
-        .filter((id) => id)
-        .map((id) => parseInt(id));
-    },
-
-    getTotalElements() {
-      if (this.settings.mode === 'cards') {
-        return this.$elements ? this.$elements.children().length : 0;
-      }
-
-      if (this.elementIndex.isIndexBusy) {
-        return null;
-      }
-      return this.elementIndex.totalUnfilteredResults;
-    },
-
-    getBaseElementOffset() {
-      if (this.settings.mode === 'cards') {
-        return 0;
-      }
-
-      return (
-        this.elementIndex.settings.batchSize * (this.elementIndex.page - 1)
-      );
-    },
-
-    createElement: async function (attributes) {
-      if (this.creatingElement) {
-        return;
-      }
-      this.creatingElement = true;
-
-      Craft.cp.announce(Craft.t('app', 'Loading'));
-
-      try {
-        await this.markAsDirty();
-
-        attributes = Object.assign(
-          {
-            elementType: this.elementType,
-            ownerId: this.settings.ownerId,
-            fieldId: this.settings.fieldId,
-            siteId: this.settings.ownerSiteId,
-          },
-          attributes
-        );
-
-        const {data} = await Craft.sendActionRequest(
-          'POST',
-          'elements/create',
-          {
-            data: attributes,
-          }
-        );
-
-        const slideout = Craft.createElementEditor(this.elementType, {
-          siteId: data.element.siteId,
-          elementId: data.element.id,
-          draftId: data.element.draftId,
-          params: {
-            fresh: 1,
-          },
-        });
-
-        let shownElement = false;
-        let $card;
-
-        const showElement = async (data) => {
-          if (!shownElement) {
-            shownElement = true;
-
-            if (this.settings.mode === 'cards') {
-              $card = await this.addElementCard(data);
-            } else {
-              this.elementIndex.clearSearch();
-              this.elementIndex.updateElements();
-            }
-
-            await this.markAsDirty();
-          }
-        };
-
-        slideout.on('load', () => {
-          slideout.elementEditor.once('afterSaveDraft', (ev) => {
-            showElement(data.element);
-          });
-        });
-
-        slideout.on('submit', async () => {
-          await showElement(data.element);
-        });
-
-        slideout.on('close', () => {
-          if (this.$createBtn) {
-            this.$createBtn.filter(':visible:first').focus();
-          }
-
-          // save the element in case any conditional fields should be shown/hidden
-          this.elementEditor?.checkForm(true);
-        });
-      } catch (e) {
-        Craft.cp.displayError(e?.response?.data?.message);
-      } finally {
-        this.creatingElement = false;
-        Craft.cp.announce(Craft.t('app', 'Loading complete'));
-      }
-    },
-
-    async duplicateElement(element) {
-      const $element = $(element);
-
-      Craft.cp.announce(Craft.t('app', 'Loading'));
-      await this.markAsDirty();
-
-      let data;
-      try {
-        const elementId = $element.data('id');
-        const response = await Craft.sendActionRequest(
-          'POST',
-          'elements/duplicate',
-          {
-            data: {
-              elementType: this.elementType,
-              ownerId: this.settings.ownerId,
-              siteId: this.settings.ownerSiteId,
-              elementId:
-                this.elementEditor?.getDraftElementId(elementId) || elementId,
-            },
-          }
-        );
-        data = response.data;
-      } catch (e) {
-        Craft.cp.displayError(e?.response?.data?.message);
-      }
-
-      const $card = await this.addElementCard(data.element);
-      $card.parent().insertAfter($element.parent());
-      await this.updateSortOrder(data.element.id);
-      // save the element in case any conditional fields should be shown/hidden
-      this.elementEditor?.checkForm(true);
-    },
-
-    async duplicateElements(elements) {
-      if (elements instanceof jQuery) {
-        elements = elements.toArray();
-      }
-
-      for (const element of elements) {
-        await this.duplicateElement(element);
-      }
-    },
-
-    async pasteElements($before = null) {
-      Craft.cp.announce(Craft.t('app', 'Loading'));
-      this.$pasteBtn.addClass('loading');
-
-      try {
-        await this.markAsDirty();
-        const newElementInfo = await Craft.cp.pasteElements(
-          Object.assign(
-            {
-              primaryOwnerId: this.settings.ownerId,
-              ownerId: this.settings.ownerId,
-              fieldId: this.settings.fieldId,
-              siteId: this.settings.ownerSiteId,
-            },
-            this.settings.pasteAttributes || {}
-          )
-        );
-
-        if (!newElementInfo.length) {
-          return;
-        }
-
-        if (this.settings.mode === 'cards') {
-          const $cards = await this.addElementCards(newElementInfo, $before);
-          await this.updateSortOrder(newElementInfo[0].id);
-          Garnish.firstFocusableElement($cards).focus();
-        } else {
-          this.elementIndex.clearSearch();
-          await this.elementIndex.updateElements();
-        }
-      } finally {
-        this.$pasteBtn.removeClass('loading');
-      }
-
-      // save the element in case any conditional fields should be shown/hidden
-      this.elementEditor?.checkForm(true);
-    },
-
-    initElement($element) {
-      setTimeout(() => {
-        if (this.settings.selectable) {
-          this.elementSelect.addItems($element);
-        }
-
-        const editable = Garnish.hasAttr($element, 'data-editable');
-
-        if (editable) {
-          // "Edit" button
-          const $editBtn = $element.find('.edit-btn');
-          if ($editBtn.length) {
-            // Override the default event listener
-            $editBtn.off('activate');
-            this.addListener($editBtn, 'activate', (ev) => {
-              // focus on the button so that when the slideout is closed, it's returned to the button
-              $editBtn.focus();
-              const cpUrl = $element.data('cpUrl');
-              if (cpUrl && Garnish.isCtrlKeyPressed(ev.originalEvent)) {
-                window.open(cpUrl);
-              } else {
-                this.createElementEditor($element);
-              }
-            });
-          }
-
-          // Double-clicks
-          this.addListener($element, 'dblclick,taphold', (ev) => {
-            if (!$(ev.target).closest('a[href],button,[role=button]').length) {
-              this.createElementEditor($element);
-            }
-          });
-        }
-
-        const actionDisclosure = $element
-          .find('.action-btn')
-          .removeClass('hidden')
-          .disclosureMenu()
-          .data('disclosureMenu');
-
-        if (actionDisclosure) {
-          const $actionMenu = actionDisclosure.$container;
-
-          const destructiveGroup = actionDisclosure.getFirstDestructiveGroup();
-          let moveUpButton,
-            moveDownButton,
-            duplicateButton,
-            copyButton,
-            pasteButton,
-            deleteButton;
-
-          const $li = $element.parent();
-          const getPrev = () => $li.prev('li');
-          const getNext = () => $li.next('li');
-
-          if (this.settings.sortable) {
-            this.elementSort?.addItems($li);
-
-            const ul = actionDisclosure.addGroup(null, true, destructiveGroup);
-
-            // Move up/forward
-            moveUpButton = actionDisclosure.addItem(
-              {
-                icon: async () =>
-                  await Craft.ui.icon(
-                    this.settings.showInGrid
-                      ? Craft.orientation === 'ltr'
-                        ? 'arrow-left'
-                        : 'arrow-right'
-                      : 'arrow-up'
-                  ),
-                label: this.settings.showInGrid
-                  ? Craft.t('app', 'Move forward')
-                  : Craft.t('app', 'Move up'),
-                onActivate: () => {
-                  const $prev = getPrev();
-                  if ($prev.length) {
-                    $li.insertBefore($prev);
-                    this.onSortChange($li);
-                  }
-                },
-              },
-              ul
-            );
-
-            // Move down/backward
-            moveDownButton = actionDisclosure.addItem(
-              {
-                icon: async () =>
-                  await Craft.ui.icon(
-                    this.settings.showInGrid
-                      ? Craft.orientation === 'ltr'
-                        ? 'arrow-right'
-                        : 'arrow-left'
-                      : 'arrow-down'
-                  ),
-                label: this.settings.showInGrid
-                  ? Craft.t('app', 'Move backward')
-                  : Craft.t('app', 'Move down'),
-                onActivate: () => {
-                  const $next = getNext();
-                  if ($next.length) {
-                    $li.insertAfter($next);
-                    this.onSortChange($li);
-                  }
-                },
-              },
-              ul
-            );
-          }
-
-          const duplicatable = Garnish.hasAttr($element, 'data-duplicatable');
-          const copyable = Garnish.hasAttr($element, 'data-copyable');
-
-          if (duplicatable || copyable) {
-            const ul = actionDisclosure.addGroup(null, true, destructiveGroup);
-
-            if (duplicatable) {
-              // Duplicate
-              duplicateButton = actionDisclosure.addItem(
-                {
-                  icon: async () => await Craft.ui.icon('clone'),
-                  label: Craft.t('app', 'Duplicate'),
-                  onActivate: () => {
-                    if (this.bulkActionMode($element)) {
-                      this.duplicateElements(
-                        this.elementSelect.getSelectedItems()
-                      );
-                    } else {
-                      this.duplicateElement($element);
-                    }
-                  },
-                },
-                ul
-              );
-            }
-
-            if (copyable) {
-              // Copy
-              const $oldCopyBtn = $actionMenu.find('[data-copy-action]');
-              if ($oldCopyBtn.length) {
-                actionDisclosure.removeItem($oldCopyBtn[0]);
-              }
-
-              copyButton = actionDisclosure.addItem(
-                {
-                  icon: async () => await Craft.ui.icon('clone-dashed'),
-                  iconColor: 'fuchsia',
-                  label: Craft.t('app', 'Copy'),
-                  onActivate: () => {
-                    if (this.bulkActionMode($element)) {
-                      Craft.cp.copyElements(
-                        this.elementSelect.getSelectedItems()
-                      );
-                    } else {
-                      Craft.cp.copyElements($element);
-                    }
-                  },
-                },
-                ul
-              );
-            }
-
-            // Paste
-            pasteButton = actionDisclosure.addItem(
-              {
-                icon: async () => await Craft.ui.icon('duplicate'),
-                iconColor: 'fuchsia',
-                label: this.settings.showInGrid
-                  ? Craft.t('app', 'Paste {type} before', {
-                      type: Craft.elementTypeNames[this.elementType][3],
-                    })
-                  : Craft.t('app', 'Paste {type} above', {
-                      type: Craft.elementTypeNames[this.elementType][3],
-                    }),
-                onActivate: async () => {
-                  if (this.canPaste(Craft.cp.getCopiedElements())) {
-                    await this.pasteElements($element.parent());
-                  }
-                },
-              },
-              ul
-            );
-          }
-
-          if (Garnish.hasAttr($element, 'data-deletable')) {
-            const ul = actionDisclosure.addGroup();
-            deleteButton = actionDisclosure.addItem(
-              {
-                icon: async () => await Craft.ui.icon('trash'),
-                label: this.settings.deleteLabel || Craft.t('app', 'Delete'),
-                destructive: true,
-                onActivate: () => {
-                  if (this.bulkActionMode($element)) {
-                    if (confirm(this.settings.bulkDeleteConfirmationMessage)) {
-                      this.deleteElements(
-                        this.elementSelect.getSelectedItems()
-                      );
-                    }
-                  } else {
-                    if (confirm(this.settings.deleteConfirmationMessage)) {
-                      this.deleteElement($element);
-                    }
-                  }
-                },
-              },
-              ul
-            );
-          }
-
-          actionDisclosure.on('show', () => {
-            const bulk = this.bulkActionMode($element);
-
-            if (moveUpButton) {
-              actionDisclosure.toggleItem(moveUpButton, getPrev().length);
-            }
-
-            if (moveDownButton) {
-              actionDisclosure.toggleItem(moveDownButton, getNext().length);
-            }
-
-            if (duplicateButton) {
-              actionDisclosure.toggleItem(duplicateButton, this.canCreate());
-
-              $(duplicateButton)
-                .children('.menu-item-label')
-                .text(
-                  bulk
-                    ? Craft.t('app', 'Duplicate selected {type}', {
-                        type: Craft.elementTypeNames[this.elementType][3],
-                      })
-                    : Craft.t('app', 'Duplicate')
-                );
-            }
-
-            if (copyButton) {
-              $(copyButton)
-                .children('.menu-item-label')
-                .text(
-                  bulk
-                    ? Craft.t('app', 'Copy selected {type}', {
-                        type: Craft.elementTypeNames[this.elementType][3],
-                      })
-                    : Craft.t('app', 'Copy')
-                );
-            }
-
-            const copiedElements = Craft.cp.getCopiedElements();
-            const showPasteButton =
-              copiedElements.length && this.canPaste(copiedElements);
-            actionDisclosure.toggleItem(pasteButton, showPasteButton);
-            if (showPasteButton) {
-              $(pasteButton)
-                .children('.menu-item-label')
-                .text(
-                  this.settings.showInGrid
-                    ? Craft.t('app', 'Paste {type} before', {
-                        type:
-                          copiedElements.length === 1
-                            ? Craft.elementTypeNames[this.elementType][2]
-                            : Craft.elementTypeNames[this.elementType][3],
-                      })
-                    : Craft.t('app', 'Paste {type} above', {
-                        type:
-                          copiedElements.length === 1
-                            ? Craft.elementTypeNames[this.elementType][2]
-                            : Craft.elementTypeNames[this.elementType][3],
-                      })
-                );
-            }
-
-            if (deleteButton) {
-              $(deleteButton)
-                .children('.menu-item-label')
-                .text(
-                  bulk
-                    ? Craft.t('app', 'Delete selected {type}', {
-                        type: Craft.elementTypeNames[this.elementType][3],
-                      })
-                    : Craft.t('app', 'Delete')
-                );
-            }
-          });
-        }
-      }, 1);
-    },
-
-    createElementEditor($element) {
-      const slideout = Craft.createElementEditor(this.elementType, $element, {
-        ownerId: this.elementEditor?.getDraftElementId(
-          $element.data('ownerId')
-        ),
-        onLoad: () => {
-          slideout.elementEditor.on('update', () => {
-            Craft.Preview.refresh();
-          });
-        },
-        onBeforeSubmit: async () => {
-          // If the nested element is primarily owned by the same owner element it was queried for,
-          // then ensure we're working with a draft and save the nested element changes to the draft
-          // note: this workflow doesn't apply to elements nested directly in global sets as globals don't use element editor
-          if (
-            typeof this.elementEditor !== 'undefined' &&
-            Garnish.hasAttr($element, 'data-owner-is-canonical') &&
-            !Garnish.hasAttr($element, 'data-is-unpublished-draft') &&
-            !this.elementEditor.settings.isUnpublishedDraft
-          ) {
-            await slideout.elementEditor.checkForm(true, true);
-            await this.markAsDirty();
-            if (
-              this.elementEditor.settings.draftId &&
-              slideout.elementEditor.settings.draftId
-            ) {
-              if (!slideout.elementEditor.settings.saveParams) {
-                slideout.elementEditor.settings.saveParams = {};
-              }
-              slideout.elementEditor.settings.saveParams.action =
-                'elements/save-nested-element-for-derivative';
-              slideout.elementEditor.settings.saveParams.newOwnerId =
-                this.settings.ownerId;
-            }
-          }
-        },
-        onSubmit: (ev) => {
-          if (ev.data.id != $element.data('id')) {
-            // swap the element with the new one
-            $element
-              .attr('data-id', ev.data.id)
-              .data('id', ev.data.id)
-              .data('owner-id', ev.data.ownerId);
-            Craft.refreshElementInstances(ev.data.id);
-          }
-        },
-      });
-    },
-
-    async deleteElement(element) {
-      const $element = $(element);
-
-      const data = Object.assign(await this.getBaseActionData(), {
-        elementId: $element.data('id'),
-      });
-
-      try {
-        const response = await Craft.sendActionRequest(
-          'POST',
-          'nested-elements/delete',
-          {data}
-        );
-        Craft.cp.displayNotice(response.data.message);
-      } catch (e) {
-        Craft.cp.displayError(e?.response?.data?.message);
-        throw e;
-      }
-
-      if (this.settings.sortable) {
-        this.elementSort?.removeItems($element);
-      }
-
-      $element.parent().remove();
-
-      // :empty isn't reliable due to text nodes
-      if (this.$elements.children().length === 0) {
-        this.deinitCards();
-      }
-
-      if (this.$createBtn) {
-        this.updateCreateBtn();
-        if (this.canCreate()) {
-          this.$createBtn.filter(':visible:first').focus();
-        }
-      }
-
-      if (!(await this.markAsDirty())) {
-        // save the element anyway in case any conditional fields should be shown/hidden
-        this.elementEditor?.checkForm(true);
-      }
-    },
-
-    async deleteElements(elements) {
-      if (elements instanceof jQuery) {
-        elements = elements.toArray();
-      }
-
-      for (const element of elements) {
-        await this.deleteElement(element);
-      }
-    },
-
-    async addElementCard(element) {
-      return await this.addElementCards([element]);
-    },
-
-    async addElementCards(elements, $before = null) {
-      if (this.creatingElement) {
-        return null;
-      }
-
-      Craft.cp.announce(Craft.t('app', 'Loading'));
-
-      let data;
-      try {
-        const response = await Craft.sendActionRequest(
-          'POST',
-          'app/render-elements',
-          {
-            data: {
-              elements: elements.map((element) => ({
-                type: this.elementType,
-                id: element.id,
-                siteId: element.siteId,
-                instances: [
-                  {
-                    context: 'field',
-                    ui: 'card',
-                    sortable: this.settings.sortable,
-                    selectable: this.settings.selectable,
-                    showActionMenu: true,
-                    hyperlink: false,
-                  },
-                ],
-              })),
-            },
-          }
-        );
-        data = response.data;
-      } catch (e) {
-        Craft.cp.displayError(e?.response?.data?.message);
-        throw e?.response?.data?.message ?? e;
-      }
-
-      if (!this.$elements) {
-        this.initCards();
-      }
-
-      let $cards = $();
-
-      for (const elementInfo of elements) {
-        for (const card of data.elements[elementInfo.id] || []) {
-          const $li = $('<li/>');
-          if ($before?.length) {
-            $li.insertBefore($before);
-          } else {
-            $li.appendTo(this.$elements);
-          }
-          const $card = $(card).appendTo($li);
-          $cards = $cards.add($card);
-          this.initElement($card);
-          Craft.cp.elementThumbLoader.load($card);
-        }
-      }
-
-      await Craft.appendHeadHtml(data.headHtml);
-      await Craft.appendBodyHtml(data.bodyHtml);
-      this.updateCreateBtn();
-
-      return $cards;
-    },
-
-    destroy: function () {
-      this.$container.removeData('nestedElementManager');
-      this.base();
-    },
-  },
-  {
-    ownerId: null,
-    defaults: {
-      mode: 'cards',
-      showInGrid: false,
-      ownerElementType: null,
-      ownerId: null,
-      ownerSiteId: null,
-      attribute: null,
-      selectable: false,
-      sortable: false,
-      indexSettings: {},
-      canCreate: false,
-      canPaste: false,
-      minElements: null,
-      maxElements: null,
-      createButtonLabel: Craft.t('app', 'Create'),
-      ownerIdParam: null,
-      createAttributes: null,
-      pasteAttributes: null,
-      fieldId: null,
-      fieldHandle: null,
-      baseInputName: null,
-      deleteLabel: null,
-      deleteConfirmationMessage: null,
-      bulkDeleteConfirmationMessage: null,
-      prevalidate: false,
-    },
-  }
-);
diff --git a/resources/js/cp.ts b/resources/js/cp.ts
index e26caa33090..c8c89b807be 100644
--- a/resources/js/cp.ts
+++ b/resources/js/cp.ts
@@ -19,6 +19,7 @@ import './modules/grouped-entry-type-manager';
 import './modules/queue';
 import './modules/slideout';
 import './modules/auth-method-setup';
+import './modules/nested-element-manager';
 
 window.Cp = Cp as unknown as typeof window.Cp;
 
diff --git a/resources/js/legacy.ts b/resources/js/legacy.ts
index c91cae93529..eac657cfca8 100644
--- a/resources/js/legacy.ts
+++ b/resources/js/legacy.ts
@@ -18,6 +18,7 @@ import './modules/grouped-entry-type-manager/index';
 import './modules/queue/index';
 import './modules/slideout/index';
 import './modules/auth-method-setup/index';
+import './modules/nested-element-manager/index';
 
 const {default: Cp} = await import('./bootstrap/cp.js');
 
diff --git a/resources/js/modules/nested-element-manager/README.md b/resources/js/modules/nested-element-manager/README.md
new file mode 100644
index 00000000000..bf09824df7f
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/README.md
@@ -0,0 +1,62 @@
+# nested-element-manager
+
+Port of the legacy `packages/craftcms-legacy/cp/src/js/NestedElementManager.js`
+(`Craft.NestedElementManager`) — the controller for nested-element card grids
+and embedded element indexes (user addresses, entries-in-entries, and any other
+PHP `NestedElementManager::getCardsHtml()` / `getIndexHtml()` surface).
+
+## What changed
+
+- `Craft.NestedElementManager` is now the modern `NestedElementManager` class
+  (`nested-element-manager.ts`) on `@craftcms/garnish` `Base`. The legacy
+  three-argument constructor signature (`container, elementType, settings`)
+  still works; the modern form folds `elementType` into the settings.
+- PHP `NestedElementManager::createView()` emits a
+  `<craft-nested-element-manager element-type="…" settings="{json}">` wrapper
+  around its rendered markup instead of a `HtmlStack::jsWithVars()` boot, so
+  the manager self-boots (and re-boots after Inertia fragment swaps) via
+  `ControllerElement`.
+- Card multi-selection and drag-sorting use modern `@craftcms/garnish`
+  `Select` / `DragSort` (same options the legacy `Garnish.Select` /
+  `Garnish.DragSort` calls passed).
+- The jQuery `.data('nestedElementManager')` back-reference became the
+  `support.ts` WeakMap, keyed by the cards/index container `div`.
+- `destroy()` now actually tears down (activate handlers, card listeners,
+  Select/DragSort, the deferred element-editor lookup) — the legacy version
+  only removed the data reference.
+
+## What stayed jQuery / legacy seams
+
+This class is an orchestrator of still-jQuery Craft widgets, so these seams
+survive (via `declare const Craft/$`):
+
+- `Craft.ui.createButton` / `createPasteButton` / `Craft.ui.icon` (jQuery factories)
+- the `disclosureMenu()` and `expandableButton()` jQuery plugins (create menu,
+  card action menus)
+- `Craft.createElementIndex` (index mode is entirely the legacy element index)
+- `Craft.createElementEditor` (edit/create slideouts)
+- the `Craft.cp` singleton: `announce`, `displayNotice`/`displayError`,
+  `copyElements`/`pasteElements`/`getCopiedElements`/`onCopyElements`,
+  `elementThumbLoader`
+- the owner form's legacy `Craft.ElementEditor`, found via
+  `$(form).data('elementEditor')`
+- `Craft.sendActionRequest`, `Craft.appendHeadHtml`/`appendBodyHtml`,
+  `Craft.Preview`, `Craft.broadcaster`, `Craft.elementTypeNames`,
+  `Craft.refreshElementInstances`, `Craft.hasMousePointerEvents`
+
+## Known warts kept for parity
+
+- `settings.canPaste` may arrive from PHP as predicate *source code* and is
+  `eval()`'d (legacy behavior).
+- `Craft.cp.onCopyElements()` has no unregister API, so the copy-listener
+  callback keeps the instance reachable until page unload even after
+  `destroy()` (legacy parity; the callback only touches the paste button).
+- `deleteElement()` passes the card (not its `li`) to `DragSort.removeItems`,
+  matching the legacy call — a no-op both before and after.
+
+## Deferred
+
+- The create/paste buttons are still legacy `Craft.ui` jQuery buttons rather
+  than `craft-button` web components (they'd need the disclosure/expandable
+  plugin equivalents first).
+- Index mode remains a thin wrapper over the legacy element index.
diff --git a/resources/js/modules/nested-element-manager/index.ts b/resources/js/modules/nested-element-manager/index.ts
new file mode 100644
index 00000000000..0557cdc73fb
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/index.ts
@@ -0,0 +1,26 @@
+import {NestedElementManager} from './nested-element-manager';
+import CraftNestedElementManager from './nested-element-manager.ce';
+import {defineElement} from '@/common/web-components';
+
+// Guarded registration (mirrors the `customElements.get()` check the
+// `@craftcms/cp` components do).
+defineElement('craft-nested-element-manager', CraftNestedElementManager);
+
+// Legacy-global shim: the legacy `Craft.NestedElementManager` no longer ships
+// in the legacy bundle, so any remaining `new Craft.NestedElementManager(
+// container, elementType, settings)` boots (plugins) resolve to the modern
+// class — its constructor still accepts the legacy three-argument signature.
+declare global {
+  interface Window {
+    Craft: any;
+  }
+}
+window.Craft = window.Craft || {};
+window.Craft.NestedElementManager = NestedElementManager;
+
+export {CraftNestedElementManager, NestedElementManager};
+export type {
+  NestedElementManagerSettings,
+  CreateAttributes,
+} from './nested-element-manager';
+export {nestedElementManagerData} from './support';
diff --git a/resources/js/modules/nested-element-manager/nested-element-manager.ce.ts b/resources/js/modules/nested-element-manager/nested-element-manager.ce.ts
new file mode 100644
index 00000000000..301f6cef20c
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/nested-element-manager.ce.ts
@@ -0,0 +1,50 @@
+import {ControllerElement} from '@/common/web-components';
+import {
+  NestedElementManager,
+  type NestedElementManagerSettings,
+} from './nested-element-manager';
+
+/**
+ * `<craft-nested-element-manager>` — boots a {@link NestedElementManager}
+ * around the server-rendered markup from PHP
+ * `NestedElementManager::getCardsHtml()` / `getIndexHtml()` that it wraps, so
+ * `NestedElementManager::createView()` can emit the element instead of a
+ * `new Craft.NestedElementManager(...)` `HtmlStack` JS boot.
+ *
+ * Configuration arrives as attributes:
+ *
+ * - `element-type` — the nested element type's class name.
+ * - `settings` — the JSON settings blob (the same shape the legacy boot
+ *   passed; see {@link NestedElementManagerSettings}), following
+ *   `<craft-field-layout-designer>`'s single-JSON-attribute precedent since
+ *   the settings include nested objects (`indexSettings`,
+ *   `createAttributes`).
+ *
+ * The element is a dumb boot/teardown wrapper: consumers reach the instance
+ * through the `support.ts` WeakMap (keyed by the inner container, matching
+ * the legacy `.data('nestedElementManager')` location), not through methods
+ * on this element. Self-boot/teardown via `ControllerElement` is what lets an
+ * Inertia page swap the fragment (e.g. after a save) and have the manager
+ * re-bind for free.
+ */
+export default class CraftNestedElementManager extends ControllerElement<NestedElementManager> {
+  // The cards container or embedded element index `div` rendered by PHP.
+  protected readonly rootSelector = ':scope > div';
+
+  protected create(root: HTMLElement): NestedElementManager {
+    const settings = this.jsonAttr(
+      'settings'
+    ) as Partial<NestedElementManagerSettings>;
+
+    return new NestedElementManager(root, {
+      ...settings,
+      elementType: this.getAttribute('element-type') ?? settings.elementType,
+    });
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'craft-nested-element-manager': CraftNestedElementManager;
+  }
+}
diff --git a/resources/js/modules/nested-element-manager/nested-element-manager.ts b/resources/js/modules/nested-element-manager/nested-element-manager.ts
new file mode 100644
index 00000000000..367fb406780
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/nested-element-manager.ts
@@ -0,0 +1,1419 @@
+import {
+  Base,
+  DragSort,
+  Select,
+  firstFocusableElement,
+  hasAttr,
+  isCtrlKeyPressed,
+  type GarnishBaseSettings,
+} from '@craftcms/garnish';
+import {nestedElementManagerData} from './support';
+
+// `Craft`, `Garnish` (legacy), and `$` (jQuery) remain page globals. This
+// class is an orchestrator of still-jQuery Craft widgets, so jQuery survives
+// at those seams: `Craft.ui.createButton`/`createPasteButton` (jQuery
+// factories), the `disclosureMenu()` / `expandableButton()` jQuery plugins,
+// `Craft.createElementIndex` (jQuery-driven element index),
+// `Craft.createElementEditor` (slideout), the `Craft.cp` singleton
+// (announce/notices/copy-paste registry/thumb loader), the legacy
+// `Craft.ElementEditor` found via `.data('elementEditor')`, and
+// `Craft.sendActionRequest`. See the module README for the seam inventory.
+declare const Craft: any;
+declare const $: any;
+
+/**
+ * The per-element-type name tuple registered in `Craft.elementTypeNames`
+ * (display name, handle, lower display name, plural lower display name).
+ */
+const typeName = (elementType: string, index: number): string =>
+  Craft.elementTypeNames[elementType]?.[index] ?? Craft.t('app', 'element');
+
+/**
+ * A `createAttributes` entry: one "New X" menu option.
+ */
+export interface CreateAttributes {
+  label: string;
+  /** SVG markup for the option icon. */
+  icon?: string | null;
+  color?: string | null;
+  group?: string | null;
+  /** The element attributes posted to `elements/create`. */
+  attributes?: Record<string, unknown>;
+}
+
+/**
+ * Settings for {@link NestedElementManager}, matching the legacy
+ * `Craft.NestedElementManager.defaults` (plus `elementType`, which the legacy
+ * class took as a separate constructor argument).
+ */
+export interface NestedElementManagerSettings extends GarnishBaseSettings {
+  /** The nested element type's class name. */
+  elementType: string;
+  /** `'cards'` for the card grid, anything else boots an embedded element index. */
+  mode: 'cards' | 'index';
+  /** Cards only: render as a wrapping grid instead of a vertical list. */
+  showInGrid: boolean;
+  ownerElementType: string | null;
+  ownerId: number | null;
+  ownerSiteId: number | null;
+  /** The owner attribute (or `field:<handle>`) the nested elements belong to. */
+  attribute: string | null;
+  selectable: boolean;
+  sortable: boolean;
+  /** Extra settings for the embedded element index (index mode). */
+  indexSettings: Record<string, unknown>;
+  canCreate: boolean;
+  /**
+   * Whether copied elements may be pasted here. May be a boolean, a predicate,
+   * or (legacy PHP settings) the *source string* of a predicate.
+   */
+  canPaste: boolean | string | ((elementInfo: any[]) => boolean);
+  minElements: number | null;
+  maxElements: number | null;
+  createButtonLabel: string;
+  /** Request param name the owner ID is sent under. */
+  ownerIdParam: string | null;
+  /** Attributes for created elements; an array renders a disclosure menu of options. */
+  createAttributes: CreateAttributes[] | Record<string, unknown> | null;
+  /** Extra params merged into paste requests. */
+  pasteAttributes: Record<string, unknown> | null;
+  fieldId: number | null;
+  fieldHandle: string | null;
+  /** Base input name used to mark the owner form dirty (delta tracking). */
+  baseInputName: string | null;
+  deleteLabel: string | null;
+  deleteConfirmationMessage: string | null;
+  bulkDeleteConfirmationMessage: string | null;
+  prevalidate: boolean;
+}
+
+/**
+ * Nested element manager — a `@craftcms/garnish` `Base` port of the legacy
+ * jQuery `Craft.NestedElementManager`, orchestrating the server-rendered
+ * markup from PHP `NestedElementManager::getCardsHtml()` /
+ * `getIndexHtml()`: a card grid (`ul.elements > li > .element`) or an
+ * embedded element index, plus the client-built New/Paste buttons and each
+ * card's action menu (move/duplicate/copy/paste/delete).
+ *
+ * Setup lives in {@link init}, invoked from the constructor only for the leaf
+ * class (`new.target` guard) — the construction contract shared by every
+ * ported module. Modern garnish supplies `Select` (card multi-selection) and
+ * `DragSort` (card drag-reordering); everything Craft-widget-shaped stays a
+ * jQuery seam (see the `declare` block above).
+ *
+ * The legacy three-argument signature — `new Craft.NestedElementManager(
+ * container, elementType, settings)` — still works for plugin boots; the
+ * modern form folds `elementType` into the settings.
+ */
+export class NestedElementManager extends Base<NestedElementManagerSettings> {
+  static defaults: Omit<NestedElementManagerSettings, 'elementType'> = {
+    mode: 'cards',
+    showInGrid: false,
+    ownerElementType: null,
+    ownerId: null,
+    ownerSiteId: null,
+    attribute: null,
+    selectable: false,
+    sortable: false,
+    indexSettings: {},
+    canCreate: false,
+    canPaste: false,
+    minElements: null,
+    maxElements: null,
+    createButtonLabel: '',
+    ownerIdParam: null,
+    createAttributes: null,
+    pasteAttributes: null,
+    fieldId: null,
+    fieldHandle: null,
+    baseInputName: null,
+    deleteLabel: null,
+    deleteConfirmationMessage: null,
+    bulkDeleteConfirmationMessage: null,
+    prevalidate: false,
+  };
+
+  /** Resolved in the constructor via `setSettings`, so never null here. */
+  declare settings: NestedElementManagerSettings;
+
+  container: HTMLElement;
+  elementType: string;
+
+  /** jQuery-wrapped create button(s); a set when grouped create menus render. */
+  $createBtn: any = null;
+  $pasteBtn: any = null;
+  /** Cards mode: the flex container the buttons append into. */
+  $btnContainer: any = null;
+
+  // Cards mode
+  /** jQuery-wrapped `ul.elements` card list. */
+  $elements: any = null;
+  elementSort: DragSort | null = null;
+  elementSelect: Select | null = null;
+
+  // Index mode
+  /** The legacy `Craft.BaseElementIndex` instance. */
+  elementIndex: any = null;
+
+  /** The owner form's legacy `Craft.ElementEditor`, if there is one. */
+  elementEditor: any = null;
+  creatingElement = false;
+
+  /** jQuery create buttons whose `activate` handlers need teardown. */
+  #activateBound: any[] = [];
+  #afterInitTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    container: HTMLElement | string,
+    elementTypeOrSettings?: string | Partial<NestedElementManagerSettings>,
+    legacySettings?: Partial<NestedElementManagerSettings>
+  ) {
+    super();
+
+    // Legacy signature: (container, elementType, settings).
+    let settings: Partial<NestedElementManagerSettings>;
+    if (typeof elementTypeOrSettings === 'string') {
+      settings = {...legacySettings, elementType: elementTypeOrSettings};
+    } else {
+      settings = elementTypeOrSettings ?? {};
+    }
+
+    const resolved =
+      typeof container === 'string'
+        ? document.querySelector<HTMLElement>(container)
+        : container;
+    if (!resolved) {
+      throw new Error('NestedElementManager: container not found.');
+    }
+    this.container = resolved;
+
+    this.setSettings(settings, {
+      ...NestedElementManager.defaults,
+      createButtonLabel: Craft.t('app', 'Create'),
+    });
+    this.elementType = this.settings.elementType;
+
+    if (new.target === NestedElementManager) {
+      this.init();
+    }
+  }
+
+  init(): void {
+    // Double instantiation guard (legacy `.data('nestedElementManager')` check).
+    const existing = nestedElementManagerData.get(this.container);
+    if (existing) {
+      console.warn(
+        'Double-instantiating a nested element manager on an element'
+      );
+      existing.destroy();
+    }
+    nestedElementManagerData.set(this.container, this);
+
+    if (this.settings.mode === 'cards') {
+      if (this.container.querySelector(':scope > .elements')) {
+        this.initCards();
+      }
+    } else {
+      this.initElementIndex();
+    }
+
+    if (this.settings.canCreate) {
+      this.#initCreateButton();
+    }
+
+    // The owner's element editor boots after this manager does; look it up a
+    // beat later (legacy parity, including the delay).
+    this.#afterInitTimeout = setTimeout(() => {
+      this.elementEditor = $(this.container)
+        .closest('form')
+        .data('elementEditor');
+
+      if (this.elementEditor) {
+        this.elementEditor.on('update', () => {
+          this.settings.ownerId = this.elementEditor.getDraftElementId(
+            this.settings.ownerId
+          );
+
+          if (this.elementIndex) {
+            this.elementIndex.settings.criteria[this.settings.ownerIdParam!] =
+              this.settings.ownerId;
+          }
+        });
+      }
+
+      this.trigger('afterInit');
+    }, 100);
+
+    // NOTE: `Craft.cp` has no unregister API for this; the callback holds this
+    // instance until the page unloads (legacy parity — see README).
+    Craft.cp.onCopyElements((elementInfo: any[], buttonLabel?: string) => {
+      this.updatePasteButton(elementInfo);
+      if (this.$pasteBtn && buttonLabel) {
+        this.$pasteBtn.find('.label').text(buttonLabel);
+      }
+    });
+  }
+
+  // --- Buttons ---------------------------------------------------------------
+
+  #initCreateButton(): void {
+    let $createBtn = Craft.ui
+      .createButton({
+        icon: 'plus',
+        label: this.settings.createButtonLabel,
+        spinner: true,
+      })
+      .addClass('icon disabled');
+
+    if (this.settings.mode === 'cards') {
+      $createBtn.addClass('dashed wrap');
+    }
+
+    this.addButton($createBtn);
+
+    if (Array.isArray(this.settings.createAttributes)) {
+      const createMenuId = `menu-${Math.floor(Math.random() * 1000000)}`;
+      $('<div/>', {
+        id: createMenuId,
+        class: 'menu menu--disclosure',
+        'data-with-search-input':
+          this.settings.createAttributes.length > 5 ? 'true' : null,
+      }).insertAfter($createBtn);
+      $createBtn
+        .attr('aria-controls', createMenuId)
+        .attr('data-disclosure-trigger', 'true')
+        .addClass('menubtn')
+        .disclosureMenu();
+      const disclosureMenu = $createBtn.data('disclosureMenu');
+
+      // can't use Object.groupBy() here because the group order matters
+      const groupedCreateAttributes: Record<string, CreateAttributes[]> = {};
+      const groupOrder: string[] = [];
+      for (const attributes of this.settings.createAttributes) {
+        const group = attributes.group || Craft.t('app', 'General');
+        if (!groupedCreateAttributes[group]) {
+          groupedCreateAttributes[group] = [];
+          groupOrder.push(group);
+        }
+        groupedCreateAttributes[group].push(attributes);
+      }
+      const multiGroup = groupOrder.length > 1;
+
+      for (const group of groupOrder) {
+        if (multiGroup) {
+          disclosureMenu.addHr();
+          disclosureMenu.addGroup(group, false);
+        }
+
+        for (const attributes of groupedCreateAttributes[group] ?? []) {
+          disclosureMenu.addItem({
+            icon: attributes.icon ? $(attributes.icon)[0] : null,
+            label: attributes.label,
+            iconColor: attributes.color,
+            onActivate: async () => {
+              $createBtn.addClass('loading');
+              await this.createElement(attributes.attributes);
+              $createBtn.removeClass('loading');
+            },
+          });
+        }
+      }
+
+      if (multiGroup && this.settings.mode === 'cards') {
+        const $collapsedContainer = $(
+          '<div class="expandable-button--collapsed"/>'
+        ).insertAfter($createBtn);
+        $collapsedContainer.append($createBtn);
+        const $expandedContainer = $(
+          '<div class="expandable-button--expanded btngroup hidden"/>'
+        ).insertAfter($collapsedContainer);
+
+        // Add a SR-only description for each disclosure button
+        const btngroupDescriptionId = `btngroup-desc-${Math.floor(
+          Math.random() * 100000
+        )}`;
+        const $btngroupDescription = $('<span>', {
+          id: btngroupDescriptionId,
+          hidden: true,
+          html: Craft.t('app', 'Create {type}', {
+            type: typeName(this.elementType, 2),
+          }),
+        });
+        $expandedContainer.append($btngroupDescription);
+
+        groupOrder.forEach((group, i) => {
+          const $groupCreateBtn = Craft.ui
+            .createButton({
+              icon: i === 0 ? 'plus' : null,
+              label: group,
+              ariaDescribedBy: btngroupDescriptionId,
+              spinner: true,
+            })
+            .addClass('icon disabled dashed')
+            .appendTo($expandedContainer);
+          const groupCreateMenuId = `menu-${Math.floor(
+            Math.random() * 1000000
+          )}`;
+          $('<div/>', {
+            id: groupCreateMenuId,
+            class: 'menu menu--disclosure',
+          }).appendTo($expandedContainer);
+          $groupCreateBtn
+            .attr('aria-controls', groupCreateMenuId)
+            .attr('data-disclosure-trigger', 'true')
+            .addClass('menubtn')
+            .disclosureMenu();
+          const groupDisclosureMenu = $groupCreateBtn.data('disclosureMenu');
+
+          for (const attributes of groupedCreateAttributes[group] ?? []) {
+            groupDisclosureMenu.addItem({
+              icon: attributes.icon ? $(attributes.icon)[0] : null,
+              label: attributes.label,
+              iconColor: attributes.color,
+              onActivate: async () => {
+                $groupCreateBtn.addClass('loading');
+                await this.createElement(attributes.attributes);
+                $groupCreateBtn.removeClass('loading');
+              },
+            });
+          }
+
+          $createBtn = $createBtn.add($groupCreateBtn);
+        });
+
+        $collapsedContainer.expandableButton();
+      }
+    } else {
+      const onActivate = async (ev: any) => {
+        ev.preventDefault();
+        $createBtn.addClass('loading');
+        await this.createElement(
+          this.settings.createAttributes as Record<string, unknown> | null
+        );
+        $createBtn.removeClass('loading');
+      };
+      $createBtn.on('activate', onActivate);
+      this.#activateBound.push($createBtn);
+    }
+
+    this.$createBtn = $createBtn;
+
+    if (this.settings.mode === 'cards') {
+      this.updateCreateBtn();
+    }
+  }
+
+  addButton($button: any): void {
+    if (this.settings.mode === 'cards') {
+      if (!this.$btnContainer) {
+        this.$btnContainer = $('<div/>', {
+          class: 'flex flex-inline',
+        }).appendTo(this.container);
+      }
+      $button.appendTo(this.$btnContainer);
+      this.updateCreateBtn();
+    } else {
+      $button.appendTo(this.elementIndex.$toolbar);
+    }
+  }
+
+  updateCreateBtn(): void {
+    if (!this.$createBtn) {
+      return;
+    }
+
+    if (this.canCreate()) {
+      this.$createBtn.removeClass('disabled');
+    } else {
+      this.$createBtn.addClass('disabled');
+    }
+
+    this.updatePasteButton();
+  }
+
+  updatePasteButton(elementInfo: any[] | null = null): void {
+    elementInfo = elementInfo || Craft.cp.getCopiedElements();
+    if (this.canPaste(elementInfo!)) {
+      if (!this.$pasteBtn) {
+        this.$pasteBtn = Craft.ui.createPasteButton();
+        this.addButton(this.$pasteBtn);
+        const onActivate = () => this.pasteElements();
+        this.$pasteBtn.on('activate', onActivate);
+        this.#activateBound.push(this.$pasteBtn);
+      } else {
+        this.$pasteBtn.removeClass('hidden');
+      }
+    } else {
+      this.$pasteBtn?.addClass('hidden');
+    }
+  }
+
+  // --- Cards mode ------------------------------------------------------------
+
+  initCards(): void {
+    this.$elements = $(this.container).children('.elements');
+
+    // Was .elements just created?
+    if (!this.$elements.length) {
+      this.$elements = $('<ul/>', {
+        class: `elements ${this.settings.showInGrid ? 'card-grid' : 'cards'}`,
+      }).prependTo(this.container);
+      $(this.container).children('.zilch').addClass('hidden');
+    }
+
+    if (this.settings.selectable) {
+      this.elementSelect = new Select(
+        this.$elements[0],
+        this.$elements.children().children('.element').toArray(),
+        {
+          multi: true,
+          vertical: !this.settings.showInGrid,
+          filter: (target: EventTarget | null) =>
+            !(target instanceof Element
+              ? target.closest(
+                  'a[href],.toggle,.btn,[role=button],.move,craft-copy-attribute'
+                )
+              : null),
+          checkboxMode: true,
+          waitForDoubleClicks: true,
+        }
+      );
+    }
+
+    // only initialise drag-sorting if the device has mouse events
+    if (this.settings.sortable && Craft.hasMousePointerEvents()) {
+      this.elementSort = new DragSort({
+        container: this.$elements[0],
+        filter: this.settings.selectable
+          ? () => {
+              // Only return all the selected items if the target item is selected
+              const target = this.elementSort!.$targetItem as unknown as
+                | HTMLElement
+                | HTMLElement[]
+                | null;
+              const targetItem = Array.isArray(target) ? target[0] : target;
+              if (
+                targetItem
+                  ?.querySelector(':scope > .element')
+                  ?.classList.contains('sel')
+              ) {
+                return this.elementSelect!.getSelectedItems()
+                  .map((element) => element.closest<HTMLElement>('li'))
+                  .filter((li): li is HTMLElement => li !== null);
+              }
+              return targetItem ? [targetItem] : [];
+            }
+          : null,
+        handle:
+          '> .element > .card-titlebar > .card-actions-container > .card-actions > .move-btn',
+        ignoreHandleSelector: null,
+        collapseDraggees: true,
+        magnetStrength: 4,
+        helperLagBase: 1.5,
+        onSortChange: () => {
+          this.onSortChange(this.elementSort!.$draggee);
+        },
+      } as any);
+    }
+
+    for (const li of Array.from(this.$elements[0].children)) {
+      const element = (li as HTMLElement).querySelector<HTMLElement>(
+        ':scope > .element'
+      );
+      if (element) {
+        this.initElement(element);
+      }
+    }
+  }
+
+  deinitCards(): void {
+    if (!this.$elements) {
+      return;
+    }
+
+    this.$elements.remove();
+    this.$elements = null;
+    this.elementSort?.destroy();
+    this.elementSort = null;
+    $(this.container).children('.zilch').removeClass('hidden');
+  }
+
+  // --- Index mode ------------------------------------------------------------
+
+  initElementIndex(): void {
+    this.elementIndex = Craft.createElementIndex(
+      this.elementType,
+      $(this.container),
+      Object.assign(
+        {
+          context: 'embedded-index',
+          sortable: this.settings.sortable,
+          prevalidate: this.settings.prevalidate,
+        },
+        this.settings.indexSettings,
+        {
+          canDuplicateElements: ($selectedItems: any) => {
+            return this.canCreate($selectedItems.length);
+          },
+          canDeleteElements: ($selectedItems: any) => {
+            return this.canDelete($selectedItems.length);
+          },
+          onBeforeMoveElementsToPage: async () => {
+            await this.markAsDirty();
+          },
+          onMoveElementsToPage: async () => {
+            await this.markAsDirty();
+          },
+          onBeforeReorderElements: async () => {
+            await this.markAsDirty();
+          },
+          onReorderElements: async () => {
+            await this.markAsDirty();
+          },
+          onBeforeDuplicateElements: async () => {
+            await this.markAsDirty();
+          },
+          onDuplicateElements: async () => {
+            await this.markAsDirty();
+          },
+          onBeforeDeleteElements: async () => {
+            await this.markAsDirty();
+          },
+          onDeleteElements: async () => {
+            if (!(await this.markAsDirty())) {
+              // save the element anyway in case any conditional fields should be shown/hidden
+              this.elementEditor?.checkForm(true);
+            }
+          },
+          onBeforeUpdateElements: () => {
+            if (this.$createBtn) {
+              this.$createBtn.addClass('disabled');
+            }
+          },
+          onCountResults: () => {
+            this.updateCreateBtn();
+          },
+          onSortChange: async ($draggee: any) => {
+            await this.onSortChange($draggee);
+          },
+        }
+      )
+    );
+  }
+
+  // --- Owner-form integration -------------------------------------------------
+
+  async markAsDirty(): Promise<boolean> {
+    if (!this.elementEditor || !this.settings.baseInputName) {
+      return false;
+    }
+    return await this.elementEditor.setFormValue(
+      this.settings.baseInputName,
+      '*'
+    );
+  }
+
+  async getBaseActionData(): Promise<Record<string, unknown>> {
+    // this could end up updating this.settings.ownerId
+    await this.markAsDirty();
+
+    return {
+      ownerElementType: this.settings.ownerElementType,
+      ownerId: this.settings.ownerId,
+      ownerSiteId: this.settings.ownerSiteId,
+      attribute: this.settings.attribute,
+    };
+  }
+
+  // --- Sorting ---------------------------------------------------------------
+
+  /**
+   * @param draggee - The dragged `li`(s): HTMLElement(s) from the modern card
+   * sorter, or a jQuery collection from the (legacy) embedded element index.
+   */
+  async onSortChange(
+    draggee: HTMLElement | HTMLElement[] | any
+  ): Promise<void> {
+    const $draggee = $(draggee);
+    const elementIds = $draggee
+      .find('.element')
+      .toArray()
+      .map((element: HTMLElement) => parseInt($(element).data('id')));
+
+    try {
+      const response = await this.updateSortOrder(elementIds);
+      Craft.cp.displayNotice(response.data.message);
+      if (Craft.broadcaster && this.elementEditor?.settings.draftId) {
+        Craft.broadcaster.postMessage({
+          pageId: Craft.pageId,
+          event: 'reorderNestedElements',
+          canonicalId: this.elementEditor.settings.canonicalId,
+          draftId: this.elementEditor.settings.draftId,
+          isProvisionalDraft: this.elementEditor.settings.isProvisionalDraft,
+          elementType: this.elementType,
+          elementIds,
+        });
+      }
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+    }
+
+    if (!(await this.markAsDirty())) {
+      // Refresh Live Preview
+      Craft.Preview.refresh();
+    }
+  }
+
+  async updateSortOrder(elementIds: number | number[]): Promise<any> {
+    const ids = (Array.isArray(elementIds) ? elementIds : [elementIds]).map(
+      (id) => parseInt(String(id))
+    );
+    const allIds = this.getElementIds();
+
+    const data = Object.assign(await this.getBaseActionData(), {
+      elementIds: ids,
+      offset: this.getBaseElementOffset() + allIds.indexOf(ids[0]!),
+    });
+
+    return await Craft.sendActionRequest('POST', 'nested-elements/reorder', {
+      data,
+    });
+  }
+
+  // --- State queries ----------------------------------------------------------
+
+  bulkActionMode(element: HTMLElement): boolean {
+    return (
+      (this.elementSelect?.totalSelected ?? 0) > 1 &&
+      (this.elementSelect?.isSelected(element) ?? false)
+    );
+  }
+
+  canCreate(num = 1): boolean {
+    if (!this.settings.canCreate || num === 0) {
+      return false;
+    }
+
+    if (!this.settings.maxElements) {
+      return true;
+    }
+
+    const total = this.getTotalElements();
+
+    return total !== null && total + num <= this.settings.maxElements;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- legacy call sites pass a count
+  canDelete(_num = 1): boolean {
+    if (!this.settings.minElements) {
+      return true;
+    }
+
+    return this.getTotalElements() !== null;
+  }
+
+  canPaste(elementInfo: any[]): boolean {
+    if (!this.settings.canPaste || !this.canCreate(elementInfo.length)) {
+      return false;
+    }
+
+    for (const e of elementInfo) {
+      if (e.type !== this.elementType) {
+        return false;
+      }
+    }
+
+    if (typeof this.settings.canPaste === 'function') {
+      return this.settings.canPaste(elementInfo);
+    }
+
+    if (typeof this.settings.canPaste === 'string') {
+      // Legacy parity: PHP settings may supply the predicate as source code.
+      return eval(this.settings.canPaste)(elementInfo);
+    }
+
+    return true;
+  }
+
+  getElementIds(): number[] {
+    let elements: HTMLElement[];
+
+    if (this.settings.mode === 'cards') {
+      elements = this.$elements.find('> li > .element').toArray();
+    } else {
+      elements = this.elementIndex.view
+        .getAllElements()
+        .toArray()
+        .map((container: HTMLElement) => container.querySelector('.element'));
+    }
+
+    return elements
+      .map((element) => element?.getAttribute('data-id'))
+      .filter((id): id is string => !!id)
+      .map((id) => parseInt(id));
+  }
+
+  getTotalElements(): number | null {
+    if (this.settings.mode === 'cards') {
+      return this.$elements ? this.$elements.children().length : 0;
+    }
+
+    if (this.elementIndex.isIndexBusy) {
+      return null;
+    }
+    return this.elementIndex.totalUnfilteredResults;
+  }
+
+  getBaseElementOffset(): number {
+    if (this.settings.mode === 'cards') {
+      return 0;
+    }
+
+    return this.elementIndex.settings.batchSize * (this.elementIndex.page - 1);
+  }
+
+  // --- Element CRUD ----------------------------------------------------------
+
+  async createElement(
+    attributes?: Record<string, unknown> | null
+  ): Promise<void> {
+    if (this.creatingElement) {
+      return;
+    }
+    this.creatingElement = true;
+
+    Craft.cp.announce(Craft.t('app', 'Loading'));
+
+    try {
+      await this.markAsDirty();
+
+      const createAttributes = Object.assign(
+        {
+          elementType: this.elementType,
+          ownerId: this.settings.ownerId,
+          fieldId: this.settings.fieldId,
+          siteId: this.settings.ownerSiteId,
+        },
+        attributes
+      );
+
+      const {data} = await Craft.sendActionRequest('POST', 'elements/create', {
+        data: createAttributes,
+      });
+
+      const slideout = Craft.createElementEditor(this.elementType, {
+        siteId: data.element.siteId,
+        elementId: data.element.id,
+        draftId: data.element.draftId,
+        params: {
+          fresh: 1,
+        },
+      });
+
+      let shownElement = false;
+
+      const showElement = async (element: any) => {
+        if (!shownElement) {
+          shownElement = true;
+
+          if (this.settings.mode === 'cards') {
+            await this.addElementCard(element);
+          } else {
+            this.elementIndex.clearSearch();
+            this.elementIndex.updateElements();
+          }
+
+          await this.markAsDirty();
+        }
+      };
+
+      slideout.on('load', () => {
+        slideout.elementEditor.once('afterSaveDraft', () => {
+          showElement(data.element);
+        });
+      });
+
+      slideout.on('submit', async () => {
+        await showElement(data.element);
+      });
+
+      slideout.on('close', () => {
+        if (this.$createBtn) {
+          this.$createBtn.filter(':visible:first').focus();
+        }
+
+        // save the element in case any conditional fields should be shown/hidden
+        this.elementEditor?.checkForm(true);
+      });
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+    } finally {
+      this.creatingElement = false;
+      Craft.cp.announce(Craft.t('app', 'Loading complete'));
+    }
+  }
+
+  async duplicateElement(element: HTMLElement): Promise<void> {
+    const $element = $(element);
+
+    Craft.cp.announce(Craft.t('app', 'Loading'));
+    await this.markAsDirty();
+
+    let data;
+    try {
+      const elementId = $element.data('id');
+      const response = await Craft.sendActionRequest(
+        'POST',
+        'elements/duplicate',
+        {
+          data: {
+            elementType: this.elementType,
+            ownerId: this.settings.ownerId,
+            siteId: this.settings.ownerSiteId,
+            elementId:
+              this.elementEditor?.getDraftElementId(elementId) || elementId,
+          },
+        }
+      );
+      data = response.data;
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+    }
+
+    const $card = await this.addElementCard(data.element);
+    $card.parent().insertAfter($element.parent());
+    await this.updateSortOrder(data.element.id);
+    // save the element in case any conditional fields should be shown/hidden
+    this.elementEditor?.checkForm(true);
+  }
+
+  async duplicateElements(elements: HTMLElement[] | any): Promise<void> {
+    for (const element of $(elements).toArray()) {
+      await this.duplicateElement(element);
+    }
+  }
+
+  async pasteElements($before: any = null): Promise<void> {
+    Craft.cp.announce(Craft.t('app', 'Loading'));
+    this.$pasteBtn.addClass('loading');
+
+    try {
+      await this.markAsDirty();
+      const newElementInfo = await Craft.cp.pasteElements(
+        Object.assign(
+          {
+            primaryOwnerId: this.settings.ownerId,
+            ownerId: this.settings.ownerId,
+            fieldId: this.settings.fieldId,
+            siteId: this.settings.ownerSiteId,
+          },
+          this.settings.pasteAttributes || {}
+        )
+      );
+
+      if (!newElementInfo.length) {
+        return;
+      }
+
+      if (this.settings.mode === 'cards') {
+        const $cards = await this.addElementCards(newElementInfo, $before);
+        await this.updateSortOrder(newElementInfo[0].id);
+        firstFocusableElement($cards[0])?.focus();
+      } else {
+        this.elementIndex.clearSearch();
+        await this.elementIndex.updateElements();
+      }
+    } finally {
+      this.$pasteBtn.removeClass('loading');
+    }
+
+    // save the element in case any conditional fields should be shown/hidden
+    this.elementEditor?.checkForm(true);
+  }
+
+  async deleteElement(element: HTMLElement): Promise<void> {
+    const $element = $(element);
+
+    const data = Object.assign(await this.getBaseActionData(), {
+      elementId: $element.data('id'),
+    });
+
+    try {
+      const response = await Craft.sendActionRequest(
+        'POST',
+        'nested-elements/delete',
+        {data}
+      );
+      Craft.cp.displayNotice(response.data.message);
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+      throw e;
+    }
+
+    if (this.settings.sortable) {
+      this.elementSort?.removeItems($element[0]);
+    }
+
+    $element.parent().remove();
+
+    // :empty isn't reliable due to text nodes
+    if (this.$elements.children().length === 0) {
+      this.deinitCards();
+    }
+
+    if (this.$createBtn) {
+      this.updateCreateBtn();
+      if (this.canCreate()) {
+        this.$createBtn.filter(':visible:first').focus();
+      }
+    }
+
+    if (!(await this.markAsDirty())) {
+      // save the element anyway in case any conditional fields should be shown/hidden
+      this.elementEditor?.checkForm(true);
+    }
+  }
+
+  async deleteElements(elements: HTMLElement[] | any): Promise<void> {
+    for (const element of $(elements).toArray()) {
+      await this.deleteElement(element);
+    }
+  }
+
+  // --- Card rendering ---------------------------------------------------------
+
+  async addElementCard(element: any): Promise<any> {
+    return await this.addElementCards([element]);
+  }
+
+  async addElementCards(elements: any[], $before: any = null): Promise<any> {
+    if (this.creatingElement) {
+      return null;
+    }
+
+    Craft.cp.announce(Craft.t('app', 'Loading'));
+
+    let data;
+    try {
+      const response = await Craft.sendActionRequest(
+        'POST',
+        'app/render-elements',
+        {
+          data: {
+            elements: elements.map((element) => ({
+              type: this.elementType,
+              id: element.id,
+              siteId: element.siteId,
+              instances: [
+                {
+                  context: 'field',
+                  ui: 'card',
+                  sortable: this.settings.sortable,
+                  selectable: this.settings.selectable,
+                  showActionMenu: true,
+                  hyperlink: false,
+                },
+              ],
+            })),
+          },
+        }
+      );
+      data = response.data;
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+      throw e?.response?.data?.message ?? e;
+    }
+
+    if (!this.$elements) {
+      this.initCards();
+    }
+
+    let $cards = $();
+
+    for (const elementInfo of elements) {
+      for (const card of data.elements[elementInfo.id] || []) {
+        const $li = $('<li/>');
+        if ($before?.length) {
+          $li.insertBefore($before);
+        } else {
+          $li.appendTo(this.$elements);
+        }
+        const $card = $(card).appendTo($li);
+        $cards = $cards.add($card);
+        this.initElement($card[0]);
+        Craft.cp.elementThumbLoader.load($card);
+      }
+    }
+
+    await Craft.appendHeadHtml(data.headHtml);
+    await Craft.appendBodyHtml(data.bodyHtml);
+    this.updateCreateBtn();
+
+    return $cards;
+  }
+
+  // --- Per-card wiring --------------------------------------------------------
+
+  initElement(element: HTMLElement): void {
+    const $element = $(element);
+
+    setTimeout(() => {
+      if (this.settings.selectable) {
+        this.elementSelect!.addItems(element);
+      }
+
+      const editable = hasAttr(element, 'data-editable');
+
+      if (editable) {
+        // "Edit" button
+        const $editBtn = $element.find('.edit-btn');
+        if ($editBtn.length) {
+          // Override the default event listener
+          $editBtn.off('activate');
+          $editBtn.on('activate', (ev: any) => {
+            // focus on the button so that when the slideout is closed, it's returned to the button
+            $editBtn.focus();
+            const cpUrl = $element.data('cpUrl');
+            if (cpUrl && isCtrlKeyPressed(ev.originalEvent ?? ev)) {
+              window.open(cpUrl);
+            } else {
+              this.createElementEditor(element);
+            }
+          });
+          this.#activateBound.push($editBtn);
+        }
+
+        // Double-clicks
+        $element.on('dblclick.nem taphold.nem', (ev: any) => {
+          if (!$(ev.target).closest('a[href],button,[role=button]').length) {
+            this.createElementEditor(element);
+          }
+        });
+      }
+
+      const actionDisclosure = $element
+        .find('.action-btn')
+        .removeClass('hidden')
+        .disclosureMenu()
+        .data('disclosureMenu');
+
+      if (actionDisclosure) {
+        this.#initElementActionMenu(element, actionDisclosure);
+      }
+    }, 1);
+  }
+
+  #initElementActionMenu(element: HTMLElement, actionDisclosure: any): void {
+    const $element = $(element);
+    const $actionMenu = actionDisclosure.$container;
+
+    const destructiveGroup = actionDisclosure.getFirstDestructiveGroup();
+    let moveUpButton: any,
+      moveDownButton: any,
+      duplicateButton: any,
+      copyButton: any,
+      pasteButton: any,
+      deleteButton: any;
+
+    const $li = $element.parent();
+    const getPrev = () => $li.prev('li');
+    const getNext = () => $li.next('li');
+
+    if (this.settings.sortable) {
+      this.elementSort?.addItems($li[0]);
+
+      const ul = actionDisclosure.addGroup(null, true, destructiveGroup);
+
+      // Move up/forward
+      moveUpButton = actionDisclosure.addItem(
+        {
+          icon: async () =>
+            await Craft.ui.icon(
+              this.settings.showInGrid
+                ? Craft.orientation === 'ltr'
+                  ? 'arrow-left'
+                  : 'arrow-right'
+                : 'arrow-up'
+            ),
+          label: this.settings.showInGrid
+            ? Craft.t('app', 'Move forward')
+            : Craft.t('app', 'Move up'),
+          onActivate: () => {
+            const $prev = getPrev();
+            if ($prev.length) {
+              $li.insertBefore($prev);
+              this.onSortChange($li);
+            }
+          },
+        },
+        ul
+      );
+
+      // Move down/backward
+      moveDownButton = actionDisclosure.addItem(
+        {
+          icon: async () =>
+            await Craft.ui.icon(
+              this.settings.showInGrid
+                ? Craft.orientation === 'ltr'
+                  ? 'arrow-right'
+                  : 'arrow-left'
+                : 'arrow-down'
+            ),
+          label: this.settings.showInGrid
+            ? Craft.t('app', 'Move backward')
+            : Craft.t('app', 'Move down'),
+          onActivate: () => {
+            const $next = getNext();
+            if ($next.length) {
+              $li.insertAfter($next);
+              this.onSortChange($li);
+            }
+          },
+        },
+        ul
+      );
+    }
+
+    const duplicatable = hasAttr(element, 'data-duplicatable');
+    const copyable = hasAttr(element, 'data-copyable');
+
+    if (duplicatable || copyable) {
+      const ul = actionDisclosure.addGroup(null, true, destructiveGroup);
+
+      if (duplicatable) {
+        // Duplicate
+        duplicateButton = actionDisclosure.addItem(
+          {
+            icon: async () => await Craft.ui.icon('clone'),
+            label: Craft.t('app', 'Duplicate'),
+            onActivate: () => {
+              if (this.bulkActionMode(element)) {
+                this.duplicateElements(this.elementSelect!.getSelectedItems());
+              } else {
+                this.duplicateElement(element);
+              }
+            },
+          },
+          ul
+        );
+      }
+
+      if (copyable) {
+        // Copy
+        const $oldCopyBtn = $actionMenu.find('[data-copy-action]');
+        if ($oldCopyBtn.length) {
+          actionDisclosure.removeItem($oldCopyBtn[0]);
+        }
+
+        copyButton = actionDisclosure.addItem(
+          {
+            icon: async () => await Craft.ui.icon('clone-dashed'),
+            iconColor: 'fuchsia',
+            label: Craft.t('app', 'Copy'),
+            onActivate: () => {
+              if (this.bulkActionMode(element)) {
+                Craft.cp.copyElements(
+                  $(this.elementSelect!.getSelectedItems())
+                );
+              } else {
+                Craft.cp.copyElements($element);
+              }
+            },
+          },
+          ul
+        );
+      }
+
+      // Paste
+      pasteButton = actionDisclosure.addItem(
+        {
+          icon: async () => await Craft.ui.icon('duplicate'),
+          iconColor: 'fuchsia',
+          label: this.settings.showInGrid
+            ? Craft.t('app', 'Paste {type} before', {
+                type: typeName(this.elementType, 3),
+              })
+            : Craft.t('app', 'Paste {type} above', {
+                type: typeName(this.elementType, 3),
+              }),
+          onActivate: async () => {
+            if (this.canPaste(Craft.cp.getCopiedElements())) {
+              await this.pasteElements($element.parent());
+            }
+          },
+        },
+        ul
+      );
+    }
+
+    if (hasAttr(element, 'data-deletable')) {
+      const ul = actionDisclosure.addGroup();
+      deleteButton = actionDisclosure.addItem(
+        {
+          icon: async () => await Craft.ui.icon('trash'),
+          label: this.settings.deleteLabel || Craft.t('app', 'Delete'),
+          destructive: true,
+          onActivate: () => {
+            if (this.bulkActionMode(element)) {
+              if (confirm(this.settings.bulkDeleteConfirmationMessage!)) {
+                this.deleteElements(this.elementSelect!.getSelectedItems());
+              }
+            } else {
+              if (confirm(this.settings.deleteConfirmationMessage!)) {
+                this.deleteElement(element);
+              }
+            }
+          },
+        },
+        ul
+      );
+    }
+
+    actionDisclosure.on('show', () => {
+      const bulk = this.bulkActionMode(element);
+
+      if (moveUpButton) {
+        actionDisclosure.toggleItem(moveUpButton, getPrev().length);
+      }
+
+      if (moveDownButton) {
+        actionDisclosure.toggleItem(moveDownButton, getNext().length);
+      }
+
+      if (duplicateButton) {
+        actionDisclosure.toggleItem(duplicateButton, this.canCreate());
+
+        $(duplicateButton)
+          .children('.menu-item-label')
+          .text(
+            bulk
+              ? Craft.t('app', 'Duplicate selected {type}', {
+                  type: typeName(this.elementType, 3),
+                })
+              : Craft.t('app', 'Duplicate')
+          );
+      }
+
+      if (copyButton) {
+        $(copyButton)
+          .children('.menu-item-label')
+          .text(
+            bulk
+              ? Craft.t('app', 'Copy selected {type}', {
+                  type: typeName(this.elementType, 3),
+                })
+              : Craft.t('app', 'Copy')
+          );
+      }
+
+      const copiedElements = Craft.cp.getCopiedElements();
+      const showPasteButton =
+        copiedElements.length && this.canPaste(copiedElements);
+      actionDisclosure.toggleItem(pasteButton, showPasteButton);
+      if (showPasteButton) {
+        $(pasteButton)
+          .children('.menu-item-label')
+          .text(
+            this.settings.showInGrid
+              ? Craft.t('app', 'Paste {type} before', {
+                  type: typeName(
+                    this.elementType,
+                    copiedElements.length === 1 ? 2 : 3
+                  ),
+                })
+              : Craft.t('app', 'Paste {type} above', {
+                  type: typeName(
+                    this.elementType,
+                    copiedElements.length === 1 ? 2 : 3
+                  ),
+                })
+          );
+      }
+
+      if (deleteButton) {
+        $(deleteButton)
+          .children('.menu-item-label')
+          .text(
+            bulk
+              ? Craft.t('app', 'Delete selected {type}', {
+                  type: typeName(this.elementType, 3),
+                })
+              : Craft.t('app', 'Delete')
+          );
+      }
+    });
+  }
+
+  createElementEditor(element: HTMLElement): void {
+    const $element = $(element);
+    const slideout = Craft.createElementEditor(this.elementType, $element, {
+      ownerId: this.elementEditor?.getDraftElementId($element.data('ownerId')),
+      onLoad: () => {
+        slideout.elementEditor.on('update', () => {
+          Craft.Preview.refresh();
+        });
+      },
+      onBeforeSubmit: async () => {
+        // If the nested element is primarily owned by the same owner element it was queried for,
+        // then ensure we're working with a draft and save the nested element changes to the draft
+        // note: this workflow doesn't apply to elements nested directly in global sets as globals don't use element editor
+        if (
+          typeof this.elementEditor !== 'undefined' &&
+          this.elementEditor !== null &&
+          hasAttr(element, 'data-owner-is-canonical') &&
+          !hasAttr(element, 'data-is-unpublished-draft') &&
+          !this.elementEditor.settings.isUnpublishedDraft
+        ) {
+          await slideout.elementEditor.checkForm(true, true);
+          await this.markAsDirty();
+          if (
+            this.elementEditor.settings.draftId &&
+            slideout.elementEditor.settings.draftId
+          ) {
+            if (!slideout.elementEditor.settings.saveParams) {
+              slideout.elementEditor.settings.saveParams = {};
+            }
+            slideout.elementEditor.settings.saveParams.action =
+              'elements/save-nested-element-for-derivative';
+            slideout.elementEditor.settings.saveParams.newOwnerId =
+              this.settings.ownerId;
+          }
+        }
+      },
+      onSubmit: (ev: any) => {
+        if (ev.data.id != $element.data('id')) {
+          // swap the element with the new one
+          $element
+            .attr('data-id', ev.data.id)
+            .data('id', ev.data.id)
+            .data('owner-id', ev.data.ownerId);
+          Craft.refreshElementInstances(ev.data.id);
+        }
+      },
+    });
+  }
+
+  // --- Teardown ---------------------------------------------------------------
+
+  override destroy(): void {
+    if (this.#afterInitTimeout !== null) {
+      clearTimeout(this.#afterInitTimeout);
+      this.#afterInitTimeout = null;
+    }
+
+    for (const $bound of this.#activateBound) {
+      $bound.off('activate');
+    }
+    this.#activateBound = [];
+    this.$elements?.children().children('.element').off('.nem');
+
+    this.elementSort?.destroy();
+    this.elementSort = null;
+    this.elementSelect?.destroy();
+    this.elementSelect = null;
+
+    nestedElementManagerData.delete(this.container);
+    super.destroy();
+  }
+}
diff --git a/resources/js/modules/nested-element-manager/support.ts b/resources/js/modules/nested-element-manager/support.ts
new file mode 100644
index 00000000000..d191ccbd0d4
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/support.ts
@@ -0,0 +1,14 @@
+import type {NestedElementManager} from './nested-element-manager';
+
+/**
+ * WeakMap replacing the legacy jQuery `.data('nestedElementManager')`
+ * back-reference (the same pattern as component-select /
+ * grouped-entry-type-manager). Keyed by the manager's container — the
+ * server-rendered cards/index `div`, not the `<craft-nested-element-manager>`
+ * wrapper — since that's the element the legacy back-reference lived on and
+ * what a `new Craft.NestedElementManager(container, …)` boot passes.
+ */
+export const nestedElementManagerData = new WeakMap<
+  Element,
+  NestedElementManager
+>();
diff --git a/src/Element/NestedElementManager.php b/src/Element/NestedElementManager.php
index 0133bdf32bc..743641d1721 100644
--- a/src/Element/NestedElementManager.php
+++ b/src/Element/NestedElementManager.php
@@ -33,6 +33,7 @@
 use CraftCms\Cms\Support\Facades\InputNamespace;
 use CraftCms\Cms\Support\Facades\Sites;
 use CraftCms\Cms\Support\Html;
+use CraftCms\Cms\Support\Json;
 use CraftCms\Cms\Support\Str;
 use Generator;
 use Illuminate\Support\Facades\DB;
@@ -305,7 +306,7 @@ function (string $id, array $config, $attribute, &$settings) use ($owner) {
 
                 $html = Html::beginTag('div', options: [
                     'id' => $id,
-                    'class' => 'nested-element-cards',
+                    'class' => 'nested-element-cards grid gap-2',
                 ]);
 
                 $value = $this->getValue($owner, true);
@@ -350,7 +351,8 @@ function (string $id, array $config, $attribute, &$settings) use ($owner) {
                     )->render();
                 }
 
-                $html .= Html::tag('div', t('Nothing yet.'), [
+                $html .= Html::tag('craft-pane', t('Nothing yet.'), [
+                    'appearance' => 'plain',
                     'class' => array_keys(array_filter([
                         'pane' => true,
                         'no-border' => true,
@@ -537,17 +539,10 @@ private function createView(?ElementInterface $owner, array $config, string $mod
 
             $html = $renderHtml($id, $config, $attribute, $settings);
 
-            HtmlStack::jsWithVars(fn ($id, $elementType, $settings) => <<<JS
-(() => {
-  new Craft.NestedElementManager('#' + $id, $elementType, $settings)
-})();
-JS, [
-                InputNamespace::namespaceId($id),
-                $this->elementType,
-                $settings,
+            return Html::tag('craft-nested-element-manager', $html, [
+                'element-type' => $this->elementType,
+                'settings' => Json::encode($settings),
             ]);
-
-            return $html;
         }, Html::id($this->field->handle ?? $attribute));
     }
 

From ea68a9ad003c12783797a952b3a55ccf116f9d3e Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 13:34:33 -0500
Subject: [PATCH 02/15] Flesh out the craft-empty component

Refines the empty-state styling (quiet fill, radius, grid-gap content
layout), registers the CraftEmpty export from the package root, and adds
Storybook stories covering the label/icon args and the graphic, content,
and default (action) slots.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/components/empty/empty.stories.ts     | 96 +++++++++++++++++++
 .../craftcms-ui/src/components/empty/empty.ts | 12 ++-
 packages/craftcms-ui/src/index.ts             |  1 +
 3 files changed, 107 insertions(+), 2 deletions(-)
 create mode 100644 packages/craftcms-ui/src/components/empty/empty.stories.ts

diff --git a/packages/craftcms-ui/src/components/empty/empty.stories.ts b/packages/craftcms-ui/src/components/empty/empty.stories.ts
new file mode 100644
index 00000000000..d3b4e234b6a
--- /dev/null
+++ b/packages/craftcms-ui/src/components/empty/empty.stories.ts
@@ -0,0 +1,96 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {html, nothing} from 'lit';
+
+import type CraftEmpty from './empty.js';
+import './empty.js';
+import '../button/button.js';
+
+// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+const meta = {
+  title: 'Components/Empty',
+  component: 'craft-empty',
+  args: {
+    label: 'Nothing yet.',
+    icon: 'magnifying-glass',
+  },
+  argTypes: {
+    label: {
+      control: {type: 'text'},
+    },
+    icon: {
+      control: {type: 'text'},
+      description: 'Icon name rendered above the label',
+    },
+  },
+  render: ({label, icon}) => {
+    return html`
+      <craft-empty label="${label}" icon="${icon || nothing}"></craft-empty>
+    `;
+  },
+} satisfies Meta<CraftEmpty>;
+
+export default meta;
+type Story = StoryObj<CraftEmpty>;
+
+// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+export const Default: Story = {
+  args: {},
+};
+
+export const LabelOnly: Story = {
+  args: {
+    icon: '',
+  },
+};
+
+export const WithAction: Story = {
+  render: ({label, icon}) => {
+    return html`
+      <craft-empty label="${label}" icon="${icon || nothing}">
+        <craft-button icon="plus">New entry</craft-button>
+      </craft-empty>
+    `;
+  },
+};
+
+export const CustomContent: Story = {
+  render: ({icon}) => {
+    return html`
+      <craft-empty icon="${icon || nothing}">
+        <div slot="content">
+          <p style="font-size: 1.25em; margin-block-end: 0">
+            No entries match your search.
+          </p>
+          <p>Try a different keyword, or clear the filters.</p>
+        </div>
+        <craft-button appearance="outline">Clear filters</craft-button>
+      </craft-empty>
+    `;
+  },
+};
+
+export const CustomGraphic: Story = {
+  render: ({label}) => {
+    return html`
+      <craft-empty label="${label}">
+        <svg
+          slot="graphic"
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke-width="1.5"
+          width="48"
+          height="48"
+          stroke="currentColor"
+        >
+          <path
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            d="M20.25 7.5l-.625 10.632a2.25 2.25 0 0 1-2.247 2.118H6.622a2.25 2.25 0 0 1-2.247-2.118L3.75 7.5m8.25 3v6.75m0 0-3-3m3 3 3-3M3.375 7.5h17.25c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125Z"
+          />
+        </svg>
+      </craft-empty>
+    `;
+  },
+};
diff --git a/packages/craftcms-ui/src/components/empty/empty.ts b/packages/craftcms-ui/src/components/empty/empty.ts
index 356d9b9d2fb..571b4ef772e 100644
--- a/packages/craftcms-ui/src/components/empty/empty.ts
+++ b/packages/craftcms-ui/src/components/empty/empty.ts
@@ -7,17 +7,25 @@ export default class CraftEmpty extends LitElement {
   static override styles = [
     css`
       .cp-empty {
-        min-height: calc(200rem / 16);
+        min-height: calc(120rem / 16);
         display: grid;
         place-items: center;
+        border-radius: var(--c-radius-md);
+        background-color: var(--c-color-neutral-fill-quiet);
+        color: var(--c-color-neutral-on-quiet);
+        padding-block: var(--c-spacing-lg);
       }
 
       .cp-empty__content {
+        display: grid; 
+        gap: var(--c-spacing-md);
+        justify-items: center;
         max-width: 60ch;
         text-align: center;
       }
 
       .label {
+        margin: 0;
         font-size: 1.25em;
       }
     `,
@@ -26,7 +34,7 @@ export default class CraftEmpty extends LitElement {
   @property() label: string = '';
   @property() icon: string = '';
 
-  protected override render(): unknown {
+  protected override render() {
     return html`
       <div class="cp-empty">
         <div class="cp-empty__content">
diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index dd43dfd4354..fb8b208928b 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -28,6 +28,7 @@ export {default as CraftCopyAttribute} from './components/copy-attribute/copy-at
 export {default as CraftCopyButton} from './components/copy-button/copy-button.js';
 export {default as CraftDialog} from './components/dialog/dialog.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';
 export {default as CraftFieldGroup} from './components/field-group/field-group.js';
 export {default as CraftIcon} from './components/icon/icon.js';

From caa1a9a6567bc9473914beb285f0ed9f2b511c99 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:45:30 -0500
Subject: [PATCH 03/15] Port the user addresses page to Inertia

AddressesController::index() now renders users/Addresses for both
myaccount/addresses and users/{id}/addresses. The address card grid (or
the >50-address element index) stays server-rendered, captured as an
HtmlFragment by the new UserAddressesViewModel and injected by the Vue
page, so the nested element manager keeps working unchanged inside the
Inertia shell.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 resources/js/pages/users/Addresses.vue        | 31 +++++++++++
 .../Controllers/Users/AddressesController.php | 23 ++------
 .../ViewModels/UserAddressesViewModel.php     | 52 +++++++++++++++++++
 .../User/AddressesControllerTest.php          | 15 ++++++
 .../TypeScriptTransformerServiceProvider.php  |  2 +
 5 files changed, 103 insertions(+), 20 deletions(-)
 create mode 100644 resources/js/pages/users/Addresses.vue
 create mode 100644 src/Http/ViewModels/UserAddressesViewModel.php

diff --git a/resources/js/pages/users/Addresses.vue b/resources/js/pages/users/Addresses.vue
new file mode 100644
index 00000000000..0f8eccc6db1
--- /dev/null
+++ b/resources/js/pages/users/Addresses.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+  import {usePage} from '@inertiajs/vue3';
+  import {t} from '@craftcms/ui';
+  import HtmlFragmentRenderer from '@/common/components/HtmlFragmentRenderer.vue';
+  import LayoutSlot from '@/common/components/LayoutSlot.vue';
+  import Pane from '@/common/components/Pane.vue';
+
+  defineOptions({
+    inheritAttrs: false,
+  });
+
+  type UserAddressesPageProps =
+    CraftCms.Cms.Http.ViewModels.UserAddressesViewModel & {
+      details?: string | null;
+    };
+
+  const props = usePage<UserAddressesPageProps>().props;
+</script>
+
+<template>
+  <Pane appearance="raised">
+    <div class="grid gap-3">
+      <h2 v-if="!props.showIndex" class="text-lg m-0!">{{ t('Addresses') }}</h2>
+      <HtmlFragmentRenderer :fragment="props.contentFragment" />
+    </div>
+  </Pane>
+
+  <LayoutSlot v-if="props.details" name="details">
+    <div v-html="props.details"></div>
+  </LayoutSlot>
+</template>
diff --git a/src/Http/Controllers/Users/AddressesController.php b/src/Http/Controllers/Users/AddressesController.php
index e816448dd0d..2aa5b110baa 100644
--- a/src/Http/Controllers/Users/AddressesController.php
+++ b/src/Http/Controllers/Users/AddressesController.php
@@ -10,7 +10,7 @@
 use CraftCms\Cms\Element\Validation\ElementRules;
 use CraftCms\Cms\Http\RespondsWithFlash;
 use CraftCms\Cms\Http\Responses\CpScreenResponse;
-use CraftCms\Cms\Support\Html;
+use CraftCms\Cms\Http\ViewModels\UserAddressesViewModel;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Gate;
 use Symfony\Component\HttpFoundation\Response;
@@ -27,25 +27,8 @@ public function index(?int $userId = null): CpScreenResponse
     {
         $user = $this->editedUser($userId);
 
-        $response = $this->asEditUserScreen($user, self::SCREEN_ADDRESSES);
-
-        $response->contentHtml(function () use ($user) {
-            $config = [
-                'showInGrid' => true,
-                'canCreate' => Gate::check('editUsers'),
-            ];
-
-            // Use an element index view if there's more than 50 addresses
-            $total = Address::find()->owner($user)->count();
-            if ($total > 50) {
-                return $user->getAddressManager()->getIndexHtml($user, $config);
-            }
-
-            return Html::tag('h2', t('Addresses')).
-                $user->getAddressManager()->getCardsHtml($user, $config);
-        });
-
-        return $response;
+        return $this->asEditUserScreen($user, self::SCREEN_ADDRESSES)
+            ->inertiaPage('users/Addresses', new UserAddressesViewModel($user));
     }
 
     public function store(Request $request, Elements $elements): Response
diff --git a/src/Http/ViewModels/UserAddressesViewModel.php b/src/Http/ViewModels/UserAddressesViewModel.php
new file mode 100644
index 00000000000..710ea7bc97a
--- /dev/null
+++ b/src/Http/ViewModels/UserAddressesViewModel.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Http\ViewModels;
+
+use CraftCms\Cms\Address\Elements\Address;
+use CraftCms\Cms\Support\Facades\HtmlStack;
+use CraftCms\Cms\User\Elements\User;
+use CraftCms\Cms\View\HtmlFragment;
+use Illuminate\Support\Facades\Gate;
+
+class UserAddressesViewModel extends ViewModel
+{
+    /**
+     * Above this many addresses, an element index replaces the card grid.
+     */
+    private const int CARD_LIMIT = 50;
+
+    private ?int $total = null;
+
+    public function __construct(
+        private readonly User $user,
+    ) {}
+
+    public function userId(): int
+    {
+        return $this->user->id;
+    }
+
+    public function showIndex(): bool
+    {
+        return $this->totalAddresses() > self::CARD_LIMIT;
+    }
+
+    public function contentFragment(): HtmlFragment
+    {
+        $config = [
+            'showInGrid' => true,
+            'canCreate' => Gate::check('editUsers'),
+        ];
+
+        return HtmlStack::capture(fn (): string => $this->showIndex()
+            ? $this->user->getAddressManager()->getIndexHtml($this->user, $config)
+            : $this->user->getAddressManager()->getCardsHtml($this->user, $config));
+    }
+
+    private function totalAddresses(): int
+    {
+        return $this->total ??= Address::find()->owner($this->user)->count();
+    }
+}
diff --git a/tests/Feature/Http/Controllers/User/AddressesControllerTest.php b/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
index c36ad350038..947d4d1a430 100644
--- a/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
+++ b/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
@@ -7,6 +7,7 @@
 use CraftCms\Cms\User\Elements\User;
 use CraftCms\Cms\User\Models\User as UserModel;
 use Illuminate\Support\Facades\DB;
+use Inertia\Testing\AssertableInertia;
 
 use function CraftCms\Cms\currentUser;
 use function CraftCms\Cms\t;
@@ -32,6 +33,20 @@
         ->assertSee(t('Addresses'));
 });
 
+test('index renders the Inertia addresses page', function () {
+    get(action([AddressesController::class, 'index']))
+        ->assertOk()
+        ->assertInertia(fn (AssertableInertia $page) => $page
+            ->component('users/Addresses')
+            ->where('userId', auth()->id())
+            ->where('showIndex', false)
+            ->where('title', t('My Account'))
+            ->has('crumbs', 2)
+            ->has('subnav')
+            ->has('details')
+            ->where('contentFragment.html', fn (string $html): bool => $html !== ''));
+});
+
 test('store & destroy', function () {
     expect(new AddressQuery()->count())->toBe(0);
 
diff --git a/workbench/app/Providers/TypeScriptTransformerServiceProvider.php b/workbench/app/Providers/TypeScriptTransformerServiceProvider.php
index 69181a21599..5ee663981e9 100644
--- a/workbench/app/Providers/TypeScriptTransformerServiceProvider.php
+++ b/workbench/app/Providers/TypeScriptTransformerServiceProvider.php
@@ -11,6 +11,7 @@
 use CraftCms\Cms\Gql\Data\GqlToken;
 use CraftCms\Cms\Http\ViewModels\FieldEditViewModel;
 use CraftCms\Cms\Http\ViewModels\FilesystemsEditViewModel;
+use CraftCms\Cms\Http\ViewModels\UserAddressesViewModel;
 use CraftCms\Cms\Http\ViewModels\UserPermissionsViewModel;
 use CraftCms\Cms\Http\ViewModels\UserPreferencesViewModel;
 use CraftCms\Cms\Http\ViewModels\UserProfileViewModel;
@@ -54,6 +55,7 @@ protected function configure(TypeScriptTransformerConfigFactory $config): void
                     Updates::class,
                     HtmlFragment::class,
                     FieldEditViewModel::class,
+                    UserAddressesViewModel::class,
                     UserPermissionsViewModel::class,
                     UserPreferencesViewModel::class,
                     UserProfileViewModel::class,

From 282de4d83bc5ab0ea17e2ad75de802e39b24185e Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:46:15 -0500
Subject: [PATCH 04/15] Add @craftcms/ui button creators and a Craft.ui
 compatibility shim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

createButton/createSubmitButton/createPasteButton in @craftcms/ui build
craft-button elements from the legacy Craft.ui config surface (plus the
modern variant/appearance/size/loading options), with the label in a
slotted span.label to preserve the legacy .find('.label') contract. New
code imports these directly.

The new resources/js/modules/ui shim patches the legacy Craft.ui methods
to delegate to the creators — returning jQuery, and bridging the legacy
style classes (disabled/loading/submit/secondary/small/big) onto the
component properties via a class-attribute observer — whether Craft.ui
is assigned before or after the shim loads. Matrix's paste button is the
first direct-import migration.

Also gives the ui package's `utilities` vitest project the same
tsconfigPaths resolution as the other projects, so utility tests can
import components.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/craftcms-ui/src/index.ts             |   1 +
 .../craftcms-ui/src/utilities/create.test.ts  |  94 ++++++++++
 packages/craftcms-ui/src/utilities/create.ts  | 174 ++++++++++++++++++
 packages/craftcms-ui/vitest.config.ts         |   3 +
 resources/js/cp.ts                            |   1 +
 resources/js/legacy.ts                        |   1 +
 resources/js/modules/matrix/interop.ts        |   1 -
 resources/js/modules/matrix/matrix-input.ts   |  32 ++--
 resources/js/modules/ui/README.md             |  47 +++++
 resources/js/modules/ui/index.ts              | 130 +++++++++++++
 10 files changed, 467 insertions(+), 17 deletions(-)
 create mode 100644 packages/craftcms-ui/src/utilities/create.test.ts
 create mode 100644 packages/craftcms-ui/src/utilities/create.ts
 create mode 100644 resources/js/modules/ui/README.md
 create mode 100644 resources/js/modules/ui/index.ts

diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index fb8b208928b..1f0893b47b8 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -82,6 +82,7 @@ export * from './utilities/string.js';
 export * from './utilities/dom.js';
 export * from './utilities/attrs.js';
 export * from './utilities/thumbnail-loader.js';
+export * from './utilities/create.js';
 
 // Services
 export {ConfigService} from './services/Config.js';
diff --git a/packages/craftcms-ui/src/utilities/create.test.ts b/packages/craftcms-ui/src/utilities/create.test.ts
new file mode 100644
index 00000000000..4bb1d9dad4f
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/create.test.ts
@@ -0,0 +1,94 @@
+import {beforeEach, describe, expect, it} from 'vitest';
+import {createButton, createPasteButton, createSubmitButton} from './create.js';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('createButton', () => {
+  it('creates a craft-button with a slotted label span', () => {
+    const button = createButton({label: 'Save'});
+
+    expect(button.tagName.toLowerCase()).toBe('craft-button');
+    expect(button.type).toBe('button');
+    const label = button.querySelector('.label');
+    expect(label).not.toBeNull();
+    expect(label!.textContent).toBe('Save');
+  });
+
+  it('applies the legacy config keys', () => {
+    const button = createButton({
+      id: 'my-btn',
+      class: 'foo bar',
+      ariaLabel: 'The button',
+      ariaDescribedBy: 'desc',
+      role: 'option',
+      toggle: true,
+      controls: 'menu-1',
+      data: {key: 'entry', count: 2},
+      icon: 'plus',
+      disabled: true,
+    });
+
+    expect(button.id).toBe('my-btn');
+    expect(button.classList.contains('foo')).toBe(true);
+    expect(button.classList.contains('bar')).toBe(true);
+    expect(button.getAttribute('aria-label')).toBe('The button');
+    expect(button.getAttribute('aria-describedby')).toBe('desc');
+    expect(button.getAttribute('role')).toBe('option');
+    expect(button.getAttribute('aria-expanded')).toBe('false');
+    expect(button.getAttribute('aria-controls')).toBe('menu-1');
+    expect(button.getAttribute('data-key')).toBe('entry');
+    expect(button.getAttribute('data-count')).toBe('2');
+    expect(button.icon).toBe('plus');
+    expect(button.disabled).toBe(true);
+  });
+
+  it('renders an html label when no plain label is given', () => {
+    const button = createButton({html: '<em>Fancy</em>'});
+
+    expect(button.querySelector('.label em')).not.toBeNull();
+  });
+
+  it('supports the modern options', () => {
+    const button = createButton({
+      variant: 'danger',
+      appearance: 'outline',
+      size: 'small',
+      loading: true,
+    });
+
+    expect(button.variant).toBe('danger');
+    expect(button.appearance).toBe('outline');
+    expect(button.size).toBe('small');
+    expect(button.loading).toBe(true);
+  });
+});
+
+describe('createSubmitButton', () => {
+  it('creates an accent submit button with the legacy class token', () => {
+    const button = createSubmitButton();
+
+    expect(button.type).toBe('submit');
+    expect(button.variant).toBe('accent');
+    expect(button.classList.contains('submit')).toBe(true);
+    expect(button.querySelector('.label')!.textContent).toBe('Submit');
+  });
+
+  it('keeps a configured label and variant', () => {
+    const button = createSubmitButton({label: 'Apply', variant: 'neutral'});
+
+    expect(button.querySelector('.label')!.textContent).toBe('Apply');
+    expect(button.variant).toBe('neutral');
+  });
+});
+
+describe('createPasteButton', () => {
+  it('creates a paste button with icon, default label, and class token', () => {
+    const button = createPasteButton();
+
+    expect(button.icon).toBe('duplicate');
+    expect(button.classList.contains('paste-btn')).toBe(true);
+    expect(button.querySelector('.label')!.textContent).toBe('Paste elements');
+  });
+});
diff --git a/packages/craftcms-ui/src/utilities/create.ts b/packages/craftcms-ui/src/utilities/create.ts
new file mode 100644
index 00000000000..424ee5ab85d
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/create.ts
@@ -0,0 +1,174 @@
+import type CraftButton from '../components/button/button.js';
+import type {
+  ButtonAppearance,
+  ButtonVariant,
+} from '../components/button/button.js';
+import '../components/button/button.js';
+import {t} from './translate.js';
+import {capitalize} from './string.js';
+
+/**
+ * Programmatic element creators — the modern replacements for the legacy
+ * `Craft.ui.create*` factories. Each returns a `@craftcms/ui` custom element
+ * (a plain `HTMLElement`, not a jQuery collection) configured through the
+ * same config keys the legacy factory accepted, plus the component's own
+ * modern options (`variant`, `appearance`, `size`).
+ *
+ * New code should import these directly. The legacy `Craft.ui.create*`
+ * methods keep working — `resources/js/modules/ui` patches them to delegate
+ * here and wraps the result for jQuery-era call sites.
+ */
+
+/**
+ * Config for {@link createButton}. The legacy keys (`class`, `html`,
+ * `spinner`, `toggle`, `controls`, …) match `Craft.ui.createButton`'s config
+ * surface so legacy call sites can migrate mechanically.
+ */
+export interface CreateButtonConfig {
+  /** The button's `type`. Defaults to `button`. */
+  type?: 'button' | 'submit' | 'reset';
+  id?: string;
+  /**
+   * Class names for the element. Legacy style classes (`disabled`,
+   * `loading`, `submit`, …) have no effect on `craft-button` by themselves —
+   * use the modern properties instead (the `Craft.ui` compatibility shim
+   * maps them for old call sites).
+   */
+  class?: string;
+  /** Plain-text label, rendered into a slotted `<span class="label">`. */
+  label?: string;
+  /** HTML label (legacy `html` key); ignored when `label` is set. */
+  html?: string;
+  /** Icon name, rendered by the component itself. */
+  icon?: string | null;
+  ariaLabel?: string;
+  ariaDescribedBy?: string;
+  role?: string;
+  /** Marks the button as a disclosure toggle (`aria-expanded="false"`). */
+  toggle?: boolean;
+  /** `aria-controls` target id. */
+  controls?: string;
+  /** `data-*` attributes. */
+  data?: Record<string, string | number | boolean>;
+  /**
+   * Legacy key: appended a spinner element. `craft-button` has a built-in
+   * spinner driven by its `loading` property, so this is accepted but
+   * ignored.
+   */
+  spinner?: boolean;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: ButtonVariant;
+  appearance?: ButtonAppearance;
+  size?: CraftButton['size'];
+}
+
+/**
+ * Creates a `<craft-button>`. The label lives in a slotted
+ * `<span class="label">`, preserving the legacy markup contract that call
+ * sites read/update the label through a `.label` child.
+ */
+export function createButton(config: CreateButtonConfig = {}): CraftButton {
+  const button = document.createElement('craft-button') as CraftButton;
+
+  button.type = config.type ?? 'button';
+
+  if (config.id) {
+    button.id = config.id;
+  }
+  if (config.class) {
+    for (const token of config.class.split(/\s+/).filter(Boolean)) {
+      button.classList.add(token);
+    }
+  }
+  if (config.ariaLabel) {
+    button.setAttribute('aria-label', config.ariaLabel);
+  }
+  if (config.ariaDescribedBy) {
+    button.setAttribute('aria-describedby', config.ariaDescribedBy);
+  }
+  if (config.role) {
+    button.setAttribute('role', config.role);
+  }
+  if (config.toggle) {
+    button.setAttribute('aria-expanded', 'false');
+  }
+  if (config.controls) {
+    button.setAttribute('aria-controls', config.controls);
+  }
+  if (config.data) {
+    for (const [key, value] of Object.entries(config.data)) {
+      button.setAttribute(`data-${key}`, String(value));
+    }
+  }
+
+  if (config.icon) {
+    button.icon = config.icon;
+  }
+
+  if (config.label || config.html) {
+    const label = document.createElement('span');
+    label.className = 'label';
+    if (config.label) {
+      label.textContent = config.label;
+    } else {
+      label.innerHTML = config.html!;
+    }
+    button.append(label);
+  }
+
+  if (config.disabled) {
+    button.disabled = true;
+  }
+  if (config.loading) {
+    button.loading = true;
+  }
+  if (config.variant) {
+    button.variant = config.variant;
+  }
+  if (config.appearance) {
+    button.appearance = config.appearance;
+  }
+  if (config.size) {
+    button.size = config.size;
+  }
+
+  return button;
+}
+
+/**
+ * Creates a submit `<craft-button>` (legacy `Craft.ui.createSubmitButton`).
+ * Accent variant by default; keeps the legacy `submit` class token for
+ * selector compatibility.
+ */
+export function createSubmitButton(
+  config: CreateButtonConfig = {}
+): CraftButton {
+  const button = createButton({
+    ...config,
+    type: 'submit',
+    label: config.label || t('Submit'),
+    variant: config.variant ?? 'accent',
+  });
+  button.classList.add('submit');
+
+  return button;
+}
+
+/**
+ * Creates a "Paste elements" `<craft-button>` (legacy
+ * `Craft.ui.createPasteButton`). Keeps the legacy `paste-btn` class token
+ * for selector compatibility.
+ */
+export function createPasteButton(
+  config: CreateButtonConfig = {}
+): CraftButton {
+  const button = createButton({
+    ...config,
+    icon: 'duplicate',
+    label: config.label || capitalize(t('Paste {type}', {type: t('elements')})),
+  });
+  button.classList.add('paste-btn');
+
+  return button;
+}
diff --git a/packages/craftcms-ui/vitest.config.ts b/packages/craftcms-ui/vitest.config.ts
index ff016216e31..3a2845fcb4c 100644
--- a/packages/craftcms-ui/vitest.config.ts
+++ b/packages/craftcms-ui/vitest.config.ts
@@ -16,6 +16,9 @@ export default defineConfig({
   test: {
     projects: [
       {
+        resolve: {
+          tsconfigPaths: true,
+        },
         test: {
           name: 'utilities',
           root: './src/utilities',
diff --git a/resources/js/cp.ts b/resources/js/cp.ts
index c8c89b807be..a1b5e22c556 100644
--- a/resources/js/cp.ts
+++ b/resources/js/cp.ts
@@ -20,6 +20,7 @@ import './modules/queue';
 import './modules/slideout';
 import './modules/auth-method-setup';
 import './modules/nested-element-manager';
+import './modules/ui';
 
 window.Cp = Cp as unknown as typeof window.Cp;
 
diff --git a/resources/js/legacy.ts b/resources/js/legacy.ts
index eac657cfca8..8ac9e96b9d7 100644
--- a/resources/js/legacy.ts
+++ b/resources/js/legacy.ts
@@ -19,6 +19,7 @@ import './modules/queue/index';
 import './modules/slideout/index';
 import './modules/auth-method-setup/index';
 import './modules/nested-element-manager/index';
+import './modules/ui/index';
 
 const {default: Cp} = await import('./bootstrap/cp.js');
 
diff --git a/resources/js/modules/matrix/interop.ts b/resources/js/modules/matrix/interop.ts
index 5975a3d2906..8c269ae07dc 100644
--- a/resources/js/modules/matrix/interop.ts
+++ b/resources/js/modules/matrix/interop.ts
@@ -125,7 +125,6 @@ export interface LegacyCraftRuntime {
     ): void;
     pasteElements(params: Record<string, unknown>): Promise<{id: number}[]>;
   };
-  ui: {createPasteButton(): unknown};
   Tabs: new (tabs: unknown) => LegacyTabs;
   FormObserver: new (
     container: unknown,
diff --git a/resources/js/modules/matrix/matrix-input.ts b/resources/js/modules/matrix/matrix-input.ts
index 8bb72d8d7d7..7b47ef7b574 100644
--- a/resources/js/modules/matrix/matrix-input.ts
+++ b/resources/js/modules/matrix/matrix-input.ts
@@ -21,7 +21,7 @@ import {
   prefersReducedMotion,
   scrollContainerToElement,
 } from '@craftcms/garnish';
-import {t} from '@craftcms/ui';
+import {createPasteButton, t, type CraftButton} from '@craftcms/ui';
 import {MatrixEntry} from './matrix-entry';
 import {containerMatrixInputs} from './support';
 import {
@@ -129,7 +129,7 @@ export class MatrixInput extends Base<MatrixInputSettings> {
   addEntryBtnContainer: HTMLElement | null = null;
   addEntryBtn: HTMLElement | null = null;
   addEntryMenuBtns: HTMLElement[] = [];
-  pasteBtn: HTMLElement | null = null;
+  pasteBtn: CraftButton | null = null;
   statusMessage: HTMLElement | null = null;
 
   entrySort: DragSort | null = null;
@@ -382,7 +382,9 @@ export class MatrixInput extends Base<MatrixInputSettings> {
 
   async pasteEntries(before: HTMLElement | null = null): Promise<void> {
     craft().cp.announce(t('Loading'));
-    this.pasteBtn?.classList.add('loading');
+    if (this.pasteBtn) {
+      this.pasteBtn.loading = true;
+    }
 
     try {
       if (this.elementEditor) {
@@ -456,7 +458,9 @@ export class MatrixInput extends Base<MatrixInputSettings> {
         firstFocusableElement(newEntries[0])?.focus();
       }
     } finally {
-      this.pasteBtn?.classList.remove('loading');
+      if (this.pasteBtn) {
+        this.pasteBtn.loading = false;
+      }
     }
 
     // Resume the element editor
@@ -485,20 +489,16 @@ export class MatrixInput extends Base<MatrixInputSettings> {
     elementInfo = elementInfo || craft().cp.getCopiedElements();
     if (this.canPaste(elementInfo)) {
       if (!this.pasteBtn) {
-        // `Craft.ui.createPasteButton()` returns a jQuery collection.
-        const created = craft().ui.createPasteButton() as {0?: HTMLElement};
-        this.pasteBtn = created[0] ?? null;
-        if (this.pasteBtn) {
-          this.addEntryBtnContainer?.append(this.pasteBtn);
-          this.addListener(this.pasteBtn, 'activate', () => {
-            this.pasteEntries();
-          });
-        }
+        this.pasteBtn = createPasteButton();
+        this.addEntryBtnContainer?.append(this.pasteBtn);
+        this.addListener(this.pasteBtn, 'activate', () => {
+          this.pasteEntries();
+        });
       } else {
-        this.pasteBtn.classList.remove('hidden');
+        this.pasteBtn.hidden = false;
       }
-    } else {
-      this.pasteBtn?.classList.add('hidden');
+    } else if (this.pasteBtn) {
+      this.pasteBtn.hidden = true;
     }
   }
 
diff --git a/resources/js/modules/ui/README.md b/resources/js/modules/ui/README.md
new file mode 100644
index 00000000000..593e0957b4d
--- /dev/null
+++ b/resources/js/modules/ui/README.md
@@ -0,0 +1,47 @@
+# ui
+
+Compatibility shim that repoints the legacy `Craft.ui.create*` factories at
+the modern `@craftcms/ui` creators, so legacy call sites produce web-component
+markup without being touched.
+
+## Shape
+
+Unlike the other modules here, this isn't a full port of a legacy file — the
+canonical implementations live in `@craftcms/ui`
+(`packages/craftcms-ui/src/utilities/create.ts`, exported from the package
+root):
+
+- `createButton(config)` → `<craft-button>`
+- `createSubmitButton(config)` → accent submit `<craft-button>`
+- `createPasteButton(config)` → "Paste elements" `<craft-button>`
+
+Each returns the **element** (not jQuery) and accepts the legacy config keys
+(`class`, `html`, `spinner`, `toggle`, `controls`, `data`, …) plus the modern
+component options (`variant`, `appearance`, `size`, `loading`). **New code
+imports these directly** and migrates `Craft.ui.create*` call sites over
+time.
+
+This module patches the corresponding `Craft.ui` methods to delegate there
+while keeping the legacy call-site contract:
+
+- returns a jQuery collection;
+- the label is a slotted `<span class="label">` (so `.find('.label')` works);
+- a `class`-attribute observer mirrors the legacy style classes onto the
+  component's properties: `disabled`/`loading` → the properties,
+  `submit` → `variant="accent"`, `secondary` → `appearance="outline"`,
+  `small`/`big` → `size`. The classes stay on the element (some double as
+  selectors); sync is one-way, class list → properties.
+- `Craft.ui` may be assigned before or after this module runs (Vite entry vs.
+  fragment-injected legacy bundle); a property setter on `Craft.ui` patches
+  the object whenever the legacy `UI.js` assigns it.
+
+## Not (yet) covered
+
+- All other `Craft.ui.create*` factories (text/select/checkbox/date/… fields)
+  still produce legacy markup. Extend the same pattern: add a creator to
+  `@craftcms/ui`, patch the method here.
+- Legacy `data-icon` attribute styling and the `dashed`/`wrap` button classes
+  have no `craft-button` equivalent yet; call sites relying on them keep the
+  classes but lose their legacy CSS once the legacy stylesheet goes away.
+- `config.spinner` is accepted and ignored — `craft-button` has a built-in
+  spinner driven by `loading`.
diff --git a/resources/js/modules/ui/index.ts b/resources/js/modules/ui/index.ts
new file mode 100644
index 00000000000..25f580051bc
--- /dev/null
+++ b/resources/js/modules/ui/index.ts
@@ -0,0 +1,130 @@
+import {
+  createButton,
+  createPasteButton,
+  createSubmitButton,
+  type CraftButton,
+  type CreateButtonConfig,
+} from '@craftcms/ui';
+
+// jQuery remains a page global — the patched `Craft.ui.create*` methods keep
+// returning jQuery collections, since that's the legacy call-site contract.
+declare const $: any;
+
+/**
+ * `Craft.ui.create*` compatibility shim.
+ *
+ * Patches the legacy `Craft.ui` button factories to build `@craftcms/ui`
+ * custom elements via the importable creators (`createButton`,
+ * `createSubmitButton`, `createPasteButton` from `@craftcms/ui`) instead of
+ * legacy `<button class="btn">` markup. The legacy call-site contract is
+ * preserved:
+ *
+ * - the methods still return a **jQuery collection** wrapping the element;
+ * - the element carries a slotted `<span class="label">`, so
+ *   `.find('.label').text(…)` keeps working;
+ * - legacy **style classes** call sites toggle (`disabled`, `loading`,
+ *   `submit`, `secondary`, `small`, `big`) are bridged onto the component's
+ *   properties by a `class`-attribute observer, so chains like
+ *   `.addClass('loading')` / `.removeClass('disabled')` still take effect.
+ *
+ * New code should import the creators directly and use the component
+ * properties instead; this shim only exists so the remaining legacy call
+ * sites migrate on their own schedule.
+ *
+ * Load order: `Craft.ui` is assigned wholesale by the legacy bundle's
+ * `UI.js`, which may load before or after this module (Vite entry vs.
+ * fragment-injected legacy bundle). When it hasn't loaded yet, a property
+ * setter on `Craft.ui` patches the object the moment it's assigned.
+ */
+
+/**
+ * Legacy style classes → component property sync. The classes stay on the
+ * element (some double as selectors, e.g. `.submit`); the observer just
+ * mirrors their presence onto the properties that actually drive the
+ * component. One-way: class list → properties.
+ */
+const CLASS_SYNCS: Array<(button: CraftButton, classes: DOMTokenList) => void> =
+  [
+    (button, classes) => {
+      button.disabled = classes.contains('disabled');
+    },
+    (button, classes) => {
+      button.loading = classes.contains('loading');
+    },
+    (button, classes) => {
+      if (classes.contains('submit')) {
+        button.variant = 'accent';
+      }
+    },
+    (button, classes) => {
+      if (classes.contains('secondary')) {
+        button.appearance = 'outline';
+      }
+    },
+    (button, classes) => {
+      if (classes.contains('small')) {
+        button.size = 'small';
+      } else if (classes.contains('big')) {
+        button.size = 'large';
+      }
+    },
+  ];
+
+function bridgeLegacyClasses(button: CraftButton): CraftButton {
+  const sync = () => {
+    for (const apply of CLASS_SYNCS) {
+      apply(button, button.classList);
+    }
+  };
+
+  sync();
+  new MutationObserver(sync).observe(button, {
+    attributes: true,
+    attributeFilter: ['class'],
+  });
+
+  return button;
+}
+
+type LegacyCreator = (config?: CreateButtonConfig) => any;
+
+function patchUi(
+  ui: Record<string, unknown> & {
+    createButton?: LegacyCreator;
+    createSubmitButton?: LegacyCreator;
+    createPasteButton?: LegacyCreator;
+  }
+): void {
+  ui.createButton = (config = {}) =>
+    $(bridgeLegacyClasses(createButton(config)));
+  ui.createSubmitButton = (config = {}) =>
+    $(bridgeLegacyClasses(createSubmitButton(config)));
+  ui.createPasteButton = (config = {}) =>
+    $(bridgeLegacyClasses(createPasteButton(config)));
+}
+
+declare global {
+  interface Window {
+    Craft: any;
+  }
+}
+
+window.Craft = window.Craft || {};
+
+if (window.Craft.ui) {
+  patchUi(window.Craft.ui);
+} else {
+  // The legacy bundle hasn't assigned `Craft.ui` yet — patch it on arrival.
+  let currentUi: any;
+  Object.defineProperty(window.Craft, 'ui', {
+    configurable: true,
+    enumerable: true,
+    get: () => currentUi,
+    set: (value) => {
+      currentUi = value;
+      if (value) {
+        patchUi(value);
+      }
+    },
+  });
+}

From aa2d2f16d8ff3d1af7a1aadf1b7a87b9a5fd3710 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:46:38 -0500
Subject: [PATCH 05/15] Use craft-empty for the nested manager empty state

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/Element/NestedElementManager.php | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/src/Element/NestedElementManager.php b/src/Element/NestedElementManager.php
index 743641d1721..a07aeae334e 100644
--- a/src/Element/NestedElementManager.php
+++ b/src/Element/NestedElementManager.php
@@ -351,13 +351,8 @@ function (string $id, array $config, $attribute, &$settings) use ($owner) {
                     )->render();
                 }
 
-                $html .= Html::tag('craft-pane', t('Nothing yet.'), [
-                    'appearance' => 'plain',
+                $html .= Html::tag('craft-empty', t('Nothing yet.'), [
                     'class' => array_keys(array_filter([
-                        'pane' => true,
-                        'no-border' => true,
-                        'zilch' => true,
-                        'small' => true,
                         'hidden' => ! empty($elements),
                     ])),
                 ]);

From e132273cc80a6221066086988f9e1e4e7d6b0882 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:47:03 -0500
Subject: [PATCH 06/15] Render nested card action menu items server-side
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The move/duplicate/copy/delete items the nested element manager used to
inject into each card's disclosure menu client-side now come down
server-rendered: ElementHtml::nestedCardActionItems() appends
behavior-less items marked data-move-forward-action /
data-move-backward-action / data-duplicate-action / data-delete-action
to the card action menu, each gated on the current user's permissions.

The signal (`showNestedActions`) is decided server-side in both render
paths: NestedElementManager::getCardsHtml() sets it for its own renders,
and app/render-elements derives it from the criterion's ownerId matching
the element's actual owner — client-supplied configs can request nothing.

Client-side, the manager only wires behavior: the marked items map to
the existing bulk-aware move/duplicate/delete flows, the element's own
server-wired Copy item is intercepted in capture phase for bulk mode,
and the clipboard-dependent Paste item is injected via
Craft.addActionsToChip. Position/limit/clipboard gating re-syncs on
every state change, replacing the legacy menu-open toggling, and the
now-dead client-side menu construction (#initElementActionMenu and the
.action-btn lookup) is removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../modules/nested-element-manager/README.md  |  10 +
 .../nested-element-manager.ts                 | 396 ++++++++----------
 src/Cp/Html/ElementHtml.php                   |  91 +++-
 src/Element/NestedElementManager.php          |   1 +
 src/Http/Controllers/App/RenderController.php |  13 +
 .../Controllers/App/RenderControllerTest.php  |  72 ++++
 .../User/AddressesControllerTest.php          |  17 +
 7 files changed, 368 insertions(+), 232 deletions(-)

diff --git a/resources/js/modules/nested-element-manager/README.md b/resources/js/modules/nested-element-manager/README.md
index bf09824df7f..3904b2e4c02 100644
--- a/resources/js/modules/nested-element-manager/README.md
+++ b/resources/js/modules/nested-element-manager/README.md
@@ -19,6 +19,16 @@ PHP `NestedElementManager::getCardsHtml()` / `getIndexHtml()` surface).
 - Card multi-selection and drag-sorting use modern `@craftcms/garnish`
   `Select` / `DragSort` (same options the legacy `Garnish.Select` /
   `Garnish.DragSort` calls passed).
+- The card action-menu items the legacy class injected client-side
+  (move up/down, duplicate, copy, delete) now come down **server-rendered**
+  with `data-*-action` markers (`ElementHtml::nestedCardActionItems()`,
+  requested via the internal `showNestedActions` card config that
+  `getCardsHtml()` and `app/render-elements` set); `initElement()` only
+  wires their behavior. Copy is the element's own server-wired item,
+  intercepted in bulk mode. Paste — clipboard-dependent — is the one
+  client-injected item (`Craft.addActionsToChip`). Position/limit/clipboard
+  gating is re-synced on every state change (`#syncCardActionItems()`)
+  instead of at menu-open time.
 - The jQuery `.data('nestedElementManager')` back-reference became the
   `support.ts` WeakMap, keyed by the cards/index container `div`.
 - `destroy()` now actually tears down (activate handlers, card listeners,
diff --git a/resources/js/modules/nested-element-manager/nested-element-manager.ts b/resources/js/modules/nested-element-manager/nested-element-manager.ts
index 367fb406780..8c4401bf4aa 100644
--- a/resources/js/modules/nested-element-manager/nested-element-manager.ts
+++ b/resources/js/modules/nested-element-manager/nested-element-manager.ts
@@ -92,8 +92,12 @@ export interface NestedElementManagerSettings extends GarnishBaseSettings {
  * jQuery `Craft.NestedElementManager`, orchestrating the server-rendered
  * markup from PHP `NestedElementManager::getCardsHtml()` /
  * `getIndexHtml()`: a card grid (`ul.elements > li > .element`) or an
- * embedded element index, plus the client-built New/Paste buttons and each
- * card's action menu (move/duplicate/copy/paste/delete).
+ * embedded element index, plus the client-built New/Paste buttons. Each
+ * card's action-menu items (move/duplicate/copy/delete) come down
+ * server-rendered with `data-*-action` markers (see
+ * `ElementHtml::nestedCardActionItems()`) and are wired to their nested
+ * flows in {@link initElement}; only the clipboard-dependent Paste item is
+ * client-injected (via `Craft.addActionsToChip`).
  *
  * Setup lives in {@link init}, invoked from the constructor only for the leaf
  * class (`new.target` guard) — the construction contract shared by every
@@ -161,6 +165,8 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
 
   /** jQuery create buttons whose `activate` handlers need teardown. */
   #activateBound: any[] = [];
+  /** Teardown callbacks for per-card native listeners (delete items, …). */
+  #disposers: Array<() => void> = [];
   #afterInitTimeout: ReturnType<typeof setTimeout> | null = null;
 
   constructor(
@@ -251,6 +257,7 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
       if (this.$pasteBtn && buttonLabel) {
         this.$pasteBtn.find('.label').text(buttonLabel);
       }
+      this.#syncCardActionItems();
     });
   }
 
@@ -418,6 +425,8 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
   }
 
   updateCreateBtn(): void {
+    this.#syncCardActionItems();
+
     if (!this.$createBtn) {
       return;
     }
@@ -458,7 +467,7 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
       this.$elements = $('<ul/>', {
         class: `elements ${this.settings.showInGrid ? 'card-grid' : 'cards'}`,
       }).prependTo(this.container);
-      $(this.container).children('.zilch').addClass('hidden');
+      $(this.container).children('craft-empty').addClass('hidden');
     }
 
     if (this.settings.selectable) {
@@ -535,7 +544,7 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
     this.$elements = null;
     this.elementSort?.destroy();
     this.elementSort = null;
-    $(this.container).children('.zilch').removeClass('hidden');
+    $(this.container).children('craft-empty').removeClass('hidden');
   }
 
   // --- Index mode ------------------------------------------------------------
@@ -634,6 +643,9 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
   async onSortChange(
     draggee: HTMLElement | HTMLElement[] | any
   ): Promise<void> {
+    // The DOM order just changed — re-gate the cards' Move items.
+    this.#syncCardActionItems();
+
     const $draggee = $(draggee);
     const elementIds = $draggee
       .find('.element')
@@ -1000,10 +1012,15 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
         'app/render-elements',
         {
           data: {
+            // `ownerId`/`fieldId` scope the element query; the server also
+            // derives which actions (e.g. Delete) belong in the card menus
+            // from that ownership — the client never decides.
             elements: elements.map((element) => ({
               type: this.elementType,
               id: element.id,
               siteId: element.siteId,
+              ownerId: this.settings.ownerId,
+              fieldId: this.settings.fieldId,
               instances: [
                 {
                   context: 'field',
@@ -1091,258 +1108,177 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
         });
       }
 
-      const actionDisclosure = $element
-        .find('.action-btn')
-        .removeClass('hidden')
-        .disclosureMenu()
-        .data('disclosureMenu');
-
-      if (actionDisclosure) {
-        this.#initElementActionMenu(element, actionDisclosure);
-      }
-    }, 1);
-  }
-
-  #initElementActionMenu(element: HTMLElement, actionDisclosure: any): void {
-    const $element = $(element);
-    const $actionMenu = actionDisclosure.$container;
-
-    const destructiveGroup = actionDisclosure.getFirstDestructiveGroup();
-    let moveUpButton: any,
-      moveDownButton: any,
-      duplicateButton: any,
-      copyButton: any,
-      pasteButton: any,
-      deleteButton: any;
-
-    const $li = $element.parent();
-    const getPrev = () => $li.prev('li');
-    const getNext = () => $li.next('li');
+      // Server-rendered nested action items (`showNestedActions` card
+      // config): the menu items carry no behavior of their own — wire them
+      // to the nested move/duplicate/delete flows here. (Copy comes down as
+      // the element's own item; we only intercept it for bulk mode. Paste is
+      // client-injected below, since it depends on clipboard state.)
+      const wireItem = (
+        selector: string,
+        handler: (ev: Event) => void,
+        options?: AddEventListenerOptions
+      ) => {
+        const item = element.querySelector<HTMLElement>(
+          `craft-action-menu [${selector}]`
+        );
+        if (item) {
+          item.addEventListener('click', handler, options);
+          this.#disposers.push(() =>
+            item.removeEventListener('click', handler, options)
+          );
+        }
+        return item;
+      };
 
-    if (this.settings.sortable) {
-      this.elementSort?.addItems($li[0]);
+      wireItem('data-move-forward-action', () => {
+        const li = element.closest('li');
+        const prev = li?.previousElementSibling;
+        if (li && prev) {
+          prev.before(li);
+          this.onSortChange($(li));
+        }
+      });
 
-      const ul = actionDisclosure.addGroup(null, true, destructiveGroup);
+      wireItem('data-move-backward-action', () => {
+        const li = element.closest('li');
+        const next = li?.nextElementSibling;
+        if (li && next) {
+          next.after(li);
+          this.onSortChange($(li));
+        }
+      });
 
-      // Move up/forward
-      moveUpButton = actionDisclosure.addItem(
-        {
-          icon: async () =>
-            await Craft.ui.icon(
-              this.settings.showInGrid
-                ? Craft.orientation === 'ltr'
-                  ? 'arrow-left'
-                  : 'arrow-right'
-                : 'arrow-up'
-            ),
-          label: this.settings.showInGrid
-            ? Craft.t('app', 'Move forward')
-            : Craft.t('app', 'Move up'),
-          onActivate: () => {
-            const $prev = getPrev();
-            if ($prev.length) {
-              $li.insertBefore($prev);
-              this.onSortChange($li);
-            }
-          },
-        },
-        ul
-      );
+      wireItem('data-duplicate-action', () => {
+        if (!this.canCreate()) {
+          return;
+        }
+        if (this.bulkActionMode(element)) {
+          this.duplicateElements(this.elementSelect!.getSelectedItems());
+        } else {
+          this.duplicateElement(element);
+        }
+      });
 
-      // Move down/backward
-      moveDownButton = actionDisclosure.addItem(
-        {
-          icon: async () =>
-            await Craft.ui.icon(
-              this.settings.showInGrid
-                ? Craft.orientation === 'ltr'
-                  ? 'arrow-right'
-                  : 'arrow-left'
-                : 'arrow-down'
-            ),
-          label: this.settings.showInGrid
-            ? Craft.t('app', 'Move backward')
-            : Craft.t('app', 'Move down'),
-          onActivate: () => {
-            const $next = getNext();
-            if ($next.length) {
-              $li.insertAfter($next);
-              this.onSortChange($li);
-            }
-          },
+      // The element's own Copy item is fully wired server-side for the
+      // single-element case; in bulk mode, take over and copy the selection
+      // instead (capture phase, so the server-bound handler never runs).
+      wireItem(
+        'data-copy-action',
+        (ev) => {
+          if (this.bulkActionMode(element)) {
+            ev.preventDefault();
+            ev.stopImmediatePropagation();
+            Craft.cp.copyElements($(this.elementSelect!.getSelectedItems()));
+            element
+              .querySelector('[data-copy-action]')
+              ?.dispatchEvent(new Event('close-overlay', {bubbles: true}));
+          }
         },
-        ul
+        {capture: true}
       );
-    }
 
-    const duplicatable = hasAttr(element, 'data-duplicatable');
-    const copyable = hasAttr(element, 'data-copyable');
-
-    if (duplicatable || copyable) {
-      const ul = actionDisclosure.addGroup(null, true, destructiveGroup);
+      wireItem('data-delete-action', () => {
+        if (this.bulkActionMode(element)) {
+          if (confirm(this.settings.bulkDeleteConfirmationMessage!)) {
+            this.deleteElements(this.elementSelect!.getSelectedItems());
+          }
+        } else if (confirm(this.settings.deleteConfirmationMessage!)) {
+          this.deleteElement(element);
+        }
+      });
 
-      if (duplicatable) {
-        // Duplicate
-        duplicateButton = actionDisclosure.addItem(
+      // Paste depends on clipboard state, so it's client-injected into the
+      // (always-rendered) menu rather than server-rendered. Guard against
+      // re-wiring the same card on a re-boot.
+      if (
+        this.settings.canPaste &&
+        !element.querySelector('[data-paste-action]')
+      ) {
+        Craft.addActionsToChip(element, [
           {
-            icon: async () => await Craft.ui.icon('clone'),
-            label: Craft.t('app', 'Duplicate'),
-            onActivate: () => {
-              if (this.bulkActionMode(element)) {
-                this.duplicateElements(this.elementSelect!.getSelectedItems());
-              } else {
-                this.duplicateElement(element);
+            icon: 'duplicate',
+            label: this.#pasteItemLabel(Craft.cp.getCopiedElements()),
+            attributes: {
+              data: {'paste-action': true},
+              'icon-color': 'fuchsia',
+            },
+            onActivate: async () => {
+              if (this.canPaste(Craft.cp.getCopiedElements())) {
+                await this.pasteElements($element.parent());
               }
             },
           },
-          ul
-        );
+        ]);
       }
 
-      if (copyable) {
-        // Copy
-        const $oldCopyBtn = $actionMenu.find('[data-copy-action]');
-        if ($oldCopyBtn.length) {
-          actionDisclosure.removeItem($oldCopyBtn[0]);
-        }
+      // Items are in place (paste injection resolves async) — sync their
+      // visibility/labels against the current state.
+      setTimeout(() => this.#syncCardActionItems());
+    }, 1);
+  }
 
-        copyButton = actionDisclosure.addItem(
-          {
-            icon: async () => await Craft.ui.icon('clone-dashed'),
-            iconColor: 'fuchsia',
-            label: Craft.t('app', 'Copy'),
-            onActivate: () => {
-              if (this.bulkActionMode(element)) {
-                Craft.cp.copyElements(
-                  $(this.elementSelect!.getSelectedItems())
-                );
-              } else {
-                Craft.cp.copyElements($element);
-              }
-            },
-          },
-          ul
-        );
-      }
+  /** The Paste item label for the current clipboard contents. */
+  #pasteItemLabel(copiedElements: any[]): string {
+    const nameIndex = copiedElements.length === 1 ? 2 : 3;
 
-      // Paste
-      pasteButton = actionDisclosure.addItem(
-        {
-          icon: async () => await Craft.ui.icon('duplicate'),
-          iconColor: 'fuchsia',
-          label: this.settings.showInGrid
-            ? Craft.t('app', 'Paste {type} before', {
-                type: typeName(this.elementType, 3),
-              })
-            : Craft.t('app', 'Paste {type} above', {
-                type: typeName(this.elementType, 3),
-              }),
-          onActivate: async () => {
-            if (this.canPaste(Craft.cp.getCopiedElements())) {
-              await this.pasteElements($element.parent());
-            }
-          },
-        },
-        ul
-      );
-    }
+    return this.settings.showInGrid
+      ? Craft.t('app', 'Paste {type} before', {
+          type: typeName(this.elementType, nameIndex),
+        })
+      : Craft.t('app', 'Paste {type} above', {
+          type: typeName(this.elementType, nameIndex),
+        });
+  }
 
-    if (hasAttr(element, 'data-deletable')) {
-      const ul = actionDisclosure.addGroup();
-      deleteButton = actionDisclosure.addItem(
-        {
-          icon: async () => await Craft.ui.icon('trash'),
-          label: this.settings.deleteLabel || Craft.t('app', 'Delete'),
-          destructive: true,
-          onActivate: () => {
-            if (this.bulkActionMode(element)) {
-              if (confirm(this.settings.bulkDeleteConfirmationMessage!)) {
-                this.deleteElements(this.elementSelect!.getSelectedItems());
-              }
-            } else {
-              if (confirm(this.settings.deleteConfirmationMessage!)) {
-                this.deleteElement(element);
-              }
-            }
-          },
-        },
-        ul
-      );
+  /**
+   * Syncs the cards' action-menu items with the current state: Duplicate
+   * against the max-elements limit, Move forward/backward against each
+   * card's position, and Paste against the clipboard (legacy parity: the
+   * injected menu toggled these at open time; the server/injected items are
+   * static, so they're re-synced whenever the state changes instead).
+   */
+  #syncCardActionItems(): void {
+    if (this.settings.mode !== 'cards' || !this.$elements?.length) {
+      return;
     }
 
-    actionDisclosure.on('show', () => {
-      const bulk = this.bulkActionMode(element);
-
-      if (moveUpButton) {
-        actionDisclosure.toggleItem(moveUpButton, getPrev().length);
-      }
+    const list = this.$elements[0] as HTMLElement;
+    const canCreate = this.canCreate();
+    const copiedElements = Craft.cp.getCopiedElements();
+    const showPaste =
+      copiedElements.length > 0 && this.canPaste(copiedElements);
+    const pasteLabel = this.#pasteItemLabel(copiedElements);
 
-      if (moveDownButton) {
-        actionDisclosure.toggleItem(moveDownButton, getNext().length);
-      }
+    for (const li of Array.from(list.children)) {
+      const item = (selector: string) =>
+        li.querySelector<HTMLElement>(`craft-action-menu [${selector}]`);
 
-      if (duplicateButton) {
-        actionDisclosure.toggleItem(duplicateButton, this.canCreate());
-
-        $(duplicateButton)
-          .children('.menu-item-label')
-          .text(
-            bulk
-              ? Craft.t('app', 'Duplicate selected {type}', {
-                  type: typeName(this.elementType, 3),
-                })
-              : Craft.t('app', 'Duplicate')
-          );
+      const forward = item('data-move-forward-action');
+      if (forward) {
+        forward.hidden = !li.previousElementSibling;
       }
 
-      if (copyButton) {
-        $(copyButton)
-          .children('.menu-item-label')
-          .text(
-            bulk
-              ? Craft.t('app', 'Copy selected {type}', {
-                  type: typeName(this.elementType, 3),
-                })
-              : Craft.t('app', 'Copy')
-          );
+      const backward = item('data-move-backward-action');
+      if (backward) {
+        backward.hidden = !li.nextElementSibling;
       }
 
-      const copiedElements = Craft.cp.getCopiedElements();
-      const showPasteButton =
-        copiedElements.length && this.canPaste(copiedElements);
-      actionDisclosure.toggleItem(pasteButton, showPasteButton);
-      if (showPasteButton) {
-        $(pasteButton)
-          .children('.menu-item-label')
-          .text(
-            this.settings.showInGrid
-              ? Craft.t('app', 'Paste {type} before', {
-                  type: typeName(
-                    this.elementType,
-                    copiedElements.length === 1 ? 2 : 3
-                  ),
-                })
-              : Craft.t('app', 'Paste {type} above', {
-                  type: typeName(
-                    this.elementType,
-                    copiedElements.length === 1 ? 2 : 3
-                  ),
-                })
-          );
+      const duplicate = item('data-duplicate-action');
+      if (duplicate) {
+        duplicate.hidden = !canCreate;
       }
 
-      if (deleteButton) {
-        $(deleteButton)
-          .children('.menu-item-label')
-          .text(
-            bulk
-              ? Craft.t('app', 'Delete selected {type}', {
-                  type: typeName(this.elementType, 3),
-                })
-              : Craft.t('app', 'Delete')
-          );
+      const paste = item('data-paste-action');
+      if (paste) {
+        paste.hidden = !showPaste;
+        const textNode = Array.from(paste.childNodes).find(
+          (node) => node.nodeType === Node.TEXT_NODE
+        );
+        if (textNode) {
+          textNode.nodeValue = pasteLabel;
+        }
       }
-    });
+    }
   }
 
   createElementEditor(element: HTMLElement): void {
@@ -1406,6 +1342,10 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
       $bound.off('activate');
     }
     this.#activateBound = [];
+    for (const dispose of this.#disposers) {
+      dispose();
+    }
+    this.#disposers = [];
     this.$elements?.children().children('.element').off('.nem');
 
     this.elementSort?.destroy();
diff --git a/src/Cp/Html/ElementHtml.php b/src/Cp/Html/ElementHtml.php
index efe8573ae31..ef12df3bf3c 100644
--- a/src/Cp/Html/ElementHtml.php
+++ b/src/Cp/Html/ElementHtml.php
@@ -24,9 +24,11 @@
 use CraftCms\Cms\Element\ElementHelper;
 use CraftCms\Cms\Element\Enums\AttributeStatus;
 use CraftCms\Cms\Element\Enums\MenuItemType;
+use CraftCms\Cms\Element\NestedElementManager;
 use CraftCms\Cms\Shared\Enums\Color;
 use CraftCms\Cms\Support\Arr;
 use CraftCms\Cms\Support\Facades\HtmlStack;
+use CraftCms\Cms\Support\Facades\I18N;
 use CraftCms\Cms\Support\Facades\InputNamespace;
 use CraftCms\Cms\Support\Html;
 use CraftCms\Cms\Support\Json;
@@ -334,6 +336,14 @@ public function elementChipHtml(ElementInterface $element, array $config = []):
      * - `inputName` – The `name` attribute that should be set on the hidden input, if `context` is set to `field`
      * - `selectable` – Whether the card should include a checkbox input
      * - `showActionMenu` – Whether the card should include an action menu
+     * - `showNestedActions` – Whether the action menu should include
+     *   behavior-less Duplicate/Delete items (marked
+     *   `data-duplicate-action`/`data-delete-action`) for the hosting
+     *   controller to wire up. A server-side signal — set by the render
+     *   paths that know the card belongs to a nested-element context
+     *   ({@see NestedElementManager::getCardsHtml()},
+     *   `app/render-elements`), never by client-supplied configs — with each
+     *   item gated on the current user's permissions
      * - `showEditButton` – Whether the card should include an edit button
      * - `sortable` – Whether the card should include a drag handle
      */
@@ -427,7 +437,7 @@ public function elementCardHeaderHtml(ElementInterface $element, array $config =
                         ])),
                     ],
                 ]) : '').
-            ($config['showActionMenu'] ? $this->componentActionMenu($element, ! $showEditButton) : '').
+            ($config['showActionMenu'] ? $this->componentActionMenu($element, ! $showEditButton, $this->nestedCardActionItems($element, $config)) : '').
             ($config['sortable'] ? Button::make()
                 ->icon('move')
                 ->attributes([
@@ -542,6 +552,7 @@ private function normalizeCardConfig(ElementInterface $element, array $config):
             'inputName' => null,
             'selectable' => false,
             'showActionMenu' => false,
+            'showNestedActions' => false,
             'showEditButton' => true,
             'sortable' => false,
         ];
@@ -554,6 +565,75 @@ private function normalizeCardConfig(ElementInterface $element, array $config):
         return $config;
     }
 
+    /**
+     * Builds the server-rendered nested-context items for a card's action
+     * menu.
+     *
+     * `showNestedActions` requests Move forward/backward (when `sortable`),
+     * Duplicate, and Delete items — marked with `data-move-forward-action`,
+     * `data-move-backward-action`, `data-duplicate-action`, and
+     * `data-delete-action` — for the hosting controller (e.g. the nested
+     * element manager) to wire up; the items carry no behavior of their own.
+     * The permission-bound items only render when the current user passes
+     * the corresponding gate (mirroring the card's
+     * `data-duplicatable`/`data-deletable` attributes), so client-supplied
+     * render configs (`app/render-elements`) can request them but never
+     * grant them.
+     */
+    private function nestedCardActionItems(ElementInterface $element, array $config): array
+    {
+        if (! $config['showNestedActions'] || ! Gate::check('view', $element)) {
+            return [];
+        }
+
+        $items = [];
+
+        if ($config['sortable']) {
+            $showInGrid = $config['showInGrid'] ?? false;
+            $ltr = I18N::getLocale()->getOrientation() === 'ltr';
+
+            $items[] = [
+                'icon' => $showInGrid ? ($ltr ? 'arrow-left' : 'arrow-right') : 'arrow-up',
+                'label' => $showInGrid ? t('Move forward') : t('Move up'),
+                'attributes' => [
+                    'data' => ['move-forward-action' => true],
+                ],
+            ];
+            $items[] = [
+                'icon' => $showInGrid ? ($ltr ? 'arrow-right' : 'arrow-left') : 'arrow-down',
+                'label' => $showInGrid ? t('Move backward') : t('Move down'),
+                'attributes' => [
+                    'data' => ['move-backward-action' => true],
+                ],
+            ];
+        }
+
+        if (Gate::check('duplicate', $element)) {
+            $items[] = [
+                'icon' => 'clone',
+                'label' => t('Duplicate'),
+                'attributes' => [
+                    'data' => ['duplicate-action' => true],
+                ],
+            ];
+        }
+
+        if (Gate::check('delete', $element)) {
+            $items[] = [
+                'icon' => 'trash',
+                'label' => mb_ucfirst(t('Delete {type}', [
+                    'type' => $element::lowerDisplayName(),
+                ])),
+                'destructive' => true,
+                'attributes' => [
+                    'data' => ['delete-action' => true],
+                ],
+            ];
+        }
+
+        return $items;
+    }
+
     /**
      * Builds the HTML attributes for the outer `.card` element.
      */
@@ -808,10 +888,10 @@ private function elementLabelHtml(ElementInterface $element, array $config, arra
      * `Craft.addActionsToChip()`) always has a `[slot="content"]` container
      * to inject into.
      */
-    private function componentActionMenu(Actionable $component, bool $withEdit = true): string
+    private function componentActionMenu(Actionable $component, bool $withEdit = true, array $extraItems = []): string
     {
         return InputNamespace::namespaceInputs(
-            function () use ($component, $withEdit): string {
+            function () use ($component, $withEdit, $extraItems): string {
                 $actionMenuItems = array_filter(
                     $component->getActionMenuItems(),
                     fn (array $item) => $item['showInChips'] ?? ! ($item['destructive'] ?? false)
@@ -833,7 +913,10 @@ function () use ($component, $withEdit): string {
                 // `disclosureMenuItems()` normalizes types, moves destructive
                 // items to the end (behind an `hr`), and trims leading/
                 // trailing/repeated `hr`s — all still desirable here.
-                $items = $this->menuHtml->disclosureMenuItems($actionMenuItems);
+                $items = $this->menuHtml->disclosureMenuItems([
+                    ...$actionMenuItems,
+                    ...$extraItems,
+                ]);
 
                 $invokerHtml = Html::tag('craft-button', Html::tag('craft-icon', '', [
                     'name' => 'ellipsis',
diff --git a/src/Element/NestedElementManager.php b/src/Element/NestedElementManager.php
index a07aeae334e..81b2a3f5bf7 100644
--- a/src/Element/NestedElementManager.php
+++ b/src/Element/NestedElementManager.php
@@ -339,6 +339,7 @@ function (string $id, array $config, $attribute, &$settings) use ($owner) {
                         fn (ElementInterface $element) => Html::li(app(ElementHtml::class)->elementCardHtml($element, [
                             'context' => 'field',
                             'showActionMenu' => true,
+                            'showNestedActions' => true,
                             'selectable' => $config['selectable'],
                             'sortable' => $config['sortable'],
                             'showInGrid' => $config['showInGrid'] ?? false,
diff --git a/src/Http/Controllers/App/RenderController.php b/src/Http/Controllers/App/RenderController.php
index 15adc587daa..732eb6284cb 100644
--- a/src/Http/Controllers/App/RenderController.php
+++ b/src/Http/Controllers/App/RenderController.php
@@ -11,6 +11,7 @@
 use CraftCms\Cms\Cp\Html\ElementHtml;
 use CraftCms\Cms\Cp\Html\MenuHtml;
 use CraftCms\Cms\Element\Contracts\ElementInterface;
+use CraftCms\Cms\Element\Contracts\NestedElementInterface;
 use CraftCms\Cms\Element\Drafts;
 use CraftCms\Cms\Element\Queries\Contracts\NestedElementQueryInterface;
 use CraftCms\Cms\Element\Validation\Rules\ElementTypeRule;
@@ -91,6 +92,18 @@ public function elements(Request $request): JsonResponse
                     $id = $element->isProvisionalDraft ? $element->getCanonicalId() : $element->id;
                     /** @var 'chip'|'card' $ui */
                     $ui = $instance['ui'] ?? 'chip';
+
+                    // Which actions belong in the rendered menus is the
+                    // server's decision: a nested element rendered for its
+                    // owner (the criterion's `ownerId`) gets its nested
+                    // Duplicate/Delete actions; client-supplied configs
+                    // can't request them.
+                    $instance['showNestedActions'] = (
+                        $ownerId !== null &&
+                        $element instanceof NestedElementInterface &&
+                        (int) $element->getOwnerId() === (int) $ownerId
+                    );
+
                     $elementHtml[$id][$key] = match ($ui) {
                         'chip' => $this->elementHtml->elementChipHtml($element, $instance),
                         'card' => $this->elementHtml->elementCardHtml($element, $instance),
diff --git a/tests/Feature/Http/Controllers/App/RenderControllerTest.php b/tests/Feature/Http/Controllers/App/RenderControllerTest.php
index 75abff93fc0..dc16fc44e5d 100644
--- a/tests/Feature/Http/Controllers/App/RenderControllerTest.php
+++ b/tests/Feature/Http/Controllers/App/RenderControllerTest.php
@@ -2,6 +2,8 @@
 
 declare(strict_types=1);
 
+use CraftCms\Cms\Address\Elements\Address;
+use CraftCms\Cms\Element\Elements;
 use CraftCms\Cms\Entry\Elements\Entry;
 use CraftCms\Cms\Entry\Models\Entry as EntryModel;
 use CraftCms\Cms\Http\Controllers\App\RenderController;
@@ -62,6 +64,76 @@
         ->assertJsonPath("elements.{$entry->id}.default", fn (string $html) => str_contains($html, 'chip') && str_contains($html, (string) $entry->id));
 });
 
+test('rendered nested element cards include the nested actions for their owner', function () {
+    $address = createOwnedAddress();
+
+    postJson(action([RenderController::class, 'elements']), [
+        'elements' => [
+            [
+                'type' => Address::class,
+                'id' => $address->id,
+                'siteId' => $address->siteId,
+                'ownerId' => auth()->id(),
+                'instances' => [
+                    ['context' => 'field', 'ui' => 'card', 'showActionMenu' => true, 'sortable' => true],
+                ],
+            ],
+        ],
+    ])
+        ->assertOk()
+        ->assertJsonPath(
+            "elements.{$address->id}.0",
+            fn (string $html) => str_contains($html, 'data-move-forward-action')
+                && str_contains($html, 'data-move-backward-action')
+                && str_contains($html, 'data-duplicate-action')
+                && str_contains($html, 'data-delete-action'),
+        );
+});
+
+test('client-supplied configs cannot request the nested actions without ownership', function () {
+    $address = createOwnedAddress();
+
+    postJson(action([RenderController::class, 'elements']), [
+        'elements' => [
+            [
+                'type' => Address::class,
+                'id' => $address->id,
+                'siteId' => $address->siteId,
+                // no ownerId — and an attempt to force the flag from the client
+                'instances' => [
+                    [
+                        'context' => 'field',
+                        'ui' => 'card',
+                        'showActionMenu' => true,
+                        'showNestedActions' => true,
+                    ],
+                ],
+            ],
+        ],
+    ])
+        ->assertOk()
+        ->assertJsonPath(
+            "elements.{$address->id}.0",
+            fn (string $html) => ! str_contains($html, 'data-duplicate-action') && ! str_contains($html, 'data-delete-action'),
+        );
+});
+
+function createOwnedAddress(): Address
+{
+    $address = new Address([
+        'ownerId' => auth()->id(),
+        'title' => 'Home',
+        'countryCode' => 'US',
+        'addressLine1' => '123 Fake Street',
+        'locality' => 'San Francisco',
+        'administrativeArea' => 'CA',
+        'postalCode' => '94107',
+    ]);
+    app(Elements::class)->saveElement($address);
+
+    return $address;
+}
+
 test('render components validates required payload', function () {
     postJson(action([RenderController::class, 'components']))
         ->assertJsonValidationErrors(['components']);
diff --git a/tests/Feature/Http/Controllers/User/AddressesControllerTest.php b/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
index 947d4d1a430..143469a9b97 100644
--- a/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
+++ b/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
@@ -33,6 +33,23 @@
         ->assertSee(t('Addresses'));
 });
 
+test('index cards include the server-rendered nested actions', function () {
+    postJson(action([AddressesController::class, 'store']), [
+        'userId' => auth()->id(),
+        'title' => 'Home',
+        'addressLine1' => '123 Fake Street',
+        'administrativeArea' => 'CA',
+        'locality' => 'San Francisco',
+        'postalCode' => '94107',
+    ])->assertOk();
+
+    get(action([AddressesController::class, 'index']))
+        ->assertOk()
+        ->assertInertia(fn (AssertableInertia $page) => $page
+            ->component('users/Addresses')
+            ->where('contentFragment.html', fn (string $html): bool => str_contains($html, 'data-duplicate-action') && str_contains($html, 'data-delete-action')));
+});
+
 test('index renders the Inertia addresses page', function () {
     get(action([AddressesController::class, 'index']))
         ->assertOk()

From 184686e2415bc077236c7f6b8c503bb4b55e1bfc Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:47:28 -0500
Subject: [PATCH 07/15] Add an elevatedFields option to useSettingsSave

Sugar over passwordConfirmation: pages can name the form fields that
require an elevated session when dirty (or '*' for any change) instead
of hand-writing the initial-value comparison predicate. The Permissions
page is the first adopter.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../settings/composables/useSettingsSave.ts   | 65 ++++++++++++++++---
 resources/js/pages/users/Permissions.vue      | 12 +---
 2 files changed, 57 insertions(+), 20 deletions(-)

diff --git a/resources/js/modules/settings/composables/useSettingsSave.ts b/resources/js/modules/settings/composables/useSettingsSave.ts
index bb497a50d62..b4df0d835a1 100644
--- a/resources/js/modules/settings/composables/useSettingsSave.ts
+++ b/resources/js/modules/settings/composables/useSettingsSave.ts
@@ -12,6 +12,14 @@ interface PasswordConfirmationOptions<T> {
 interface UseSettingsSaveOptions<T extends Record<string, any>> {
   transform?: (data: T) => Record<string, any>;
   passwordConfirmation?: PasswordConfirmationOptions<T>;
+  /**
+   * Sugar over {@link passwordConfirmation}: require an elevated session when the
+   * named fields differ from their initial values, or `'*'` for any dirty change
+   * (via Inertia's `form.isDirty`). Ignored when `passwordConfirmation` is set
+   * explicitly — reach for that when you need a custom predicate or
+   * `minimumRemainingSeconds`.
+   */
+  elevatedFields?: Array<keyof T> | '*';
 }
 
 export function useSettingsSave<T extends Record<string, any>>(
@@ -24,6 +32,13 @@ export function useSettingsSave<T extends Record<string, any>>(
   }>();
   const redirectUrl = computed(() => page.props.redirectUrl);
 
+  // `elevatedFields` is sugar that generates a `passwordConfirmation` config, so
+  // the proactive check and the 423 retry below both flow through one path. An
+  // explicit `passwordConfirmation` always wins.
+  const passwordConfirmation =
+    options.passwordConfirmation ??
+    elevatedFieldsConfirmation(form, options.elevatedFields);
+
   // Handle cmd + s events
   useEventListener('keydown', (event) => {
     if ((event.metaKey || event.ctrlKey) && event.key === 's') {
@@ -64,11 +79,7 @@ export function useSettingsSave<T extends Record<string, any>>(
         .submit(action(), {
           ...submitOptions,
           onHttpException: (response) => {
-            if (
-              !options.passwordConfirmation ||
-              response.status !== 423 ||
-              retried
-            ) {
+            if (!passwordConfirmation || response.status !== 423 || retried) {
               return;
             }
 
@@ -76,7 +87,7 @@ export function useSettingsSave<T extends Record<string, any>>(
               .require({
                 force: true,
                 minimumRemainingSeconds:
-                  options.passwordConfirmation?.minimumRemainingSeconds,
+                  passwordConfirmation.minimumRemainingSeconds,
               })
               .then((confirmed) => {
                 if (confirmed) {
@@ -89,11 +100,10 @@ export function useSettingsSave<T extends Record<string, any>>(
         });
     }
 
-    if (options.passwordConfirmation?.required(form.data())) {
+    if (passwordConfirmation?.required(form.data())) {
       elevatedSessionManager
         .require({
-          minimumRemainingSeconds:
-            options.passwordConfirmation.minimumRemainingSeconds,
+          minimumRemainingSeconds: passwordConfirmation.minimumRemainingSeconds,
         })
         .then((confirmed) => {
           if (confirmed) {
@@ -109,3 +119,40 @@ export function useSettingsSave<T extends Record<string, any>>(
 
   return {save};
 }
+
+/**
+ * Build a {@link PasswordConfirmationOptions} from the `elevatedFields` sugar.
+ * An array snapshots each field's initial value and requires elevation when any
+ * changes; `'*'` defers to Inertia's own dirty tracking.
+ */
+function elevatedFieldsConfirmation<T extends Record<string, any>>(
+  form: InertiaForm<T>,
+  fields: Array<keyof T> | '*' | undefined
+): PasswordConfirmationOptions<T> | undefined {
+  if (!fields) {
+    return undefined;
+  }
+
+  if (fields === '*') {
+    return {required: () => form.isDirty};
+  }
+
+  const baseline = new Map<keyof T, string>(
+    fields.map((field) => [field, normalize(form[field])])
+  );
+
+  return {
+    required: (data) =>
+      fields.some((field) => normalize(data[field]) !== baseline.get(field)),
+  };
+}
+
+/**
+ * Stringify a field value for change comparison. Arrays are sorted first so a set
+ * of permissions/groups compares equal regardless of order.
+ */
+function normalize(value: unknown): string {
+  return Array.isArray(value)
+    ? JSON.stringify([...value].sort())
+    : JSON.stringify(value);
+}
diff --git a/resources/js/pages/users/Permissions.vue b/resources/js/pages/users/Permissions.vue
index 998326c4ca7..709f00d7940 100644
--- a/resources/js/pages/users/Permissions.vue
+++ b/resources/js/pages/users/Permissions.vue
@@ -28,9 +28,6 @@
     groups: props.currentGroupIds,
     permissions: props.directPermissions,
   });
-  const initialAdmin = form.admin;
-  const initialGroups = new Set(form.groups);
-  const initialPermissions = new Set(form.permissions);
 
   const routeAction = () =>
     props.user.isCurrent
@@ -40,14 +37,7 @@
         });
 
   const {save} = useSettingsSave(form, routeAction, {
-    passwordConfirmation: {
-      required: ({admin, groups, permissions}) =>
-        admin !== initialAdmin ||
-        groups.length !== initialGroups.size ||
-        groups.some((group) => !initialGroups.has(group)) ||
-        permissions.length !== initialPermissions.size ||
-        permissions.some((permission) => !initialPermissions.has(permission)),
-    },
+    elevatedFields: ['admin', 'groups', 'permissions'],
   });
 
   const lockedPermissions = computed(() => [

From 07cad1689be547c52d3a248c1e8958a55b96f5f4 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:47:40 -0500
Subject: [PATCH 08/15] Restore the legacy cp.css registration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-enables the legacy stylesheet in CpAsset — slideout chrome and other
legacy surfaces still depend on it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/View/LegacyAssets/CpAsset.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/View/LegacyAssets/CpAsset.php b/src/View/LegacyAssets/CpAsset.php
index 909cc05574e..d07c16406bf 100644
--- a/src/View/LegacyAssets/CpAsset.php
+++ b/src/View/LegacyAssets/CpAsset.php
@@ -43,7 +43,7 @@ class CpAsset implements LegacyAssetInterface
     public function register(HtmlStack $htmlStack): void
     {
         // CP
-        // $htmlStack->cssFile(craftAsset('legacy/cp/dist/css/cp.css'));
+        $htmlStack->cssFile(craftAsset('legacy/cp/dist/css/cp.css'));
         $htmlStack->jsFile(craftAsset('legacy/cp/dist/cp.js'));
 
         $htmlStack->icons([

From 1c991952cec8d73062fe793eb6e2229a7d16e265 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 21:55:37 -0500
Subject: [PATCH 09/15] Cleanup button styling

---
 src/Cp/Html/ElementHtml.php | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/Cp/Html/ElementHtml.php b/src/Cp/Html/ElementHtml.php
index ef12df3bf3c..575ac9af212 100644
--- a/src/Cp/Html/ElementHtml.php
+++ b/src/Cp/Html/ElementHtml.php
@@ -16,6 +16,7 @@
 use CraftCms\Cms\Component\Contracts\Thumbable;
 use CraftCms\Cms\Cp\Components\Button;
 use CraftCms\Cms\Cp\Components\Icon;
+use CraftCms\Cms\Cp\Enums\Appearance;
 use CraftCms\Cms\Cp\Events\ElementCardHtmlResolving;
 use CraftCms\Cms\Cp\Events\ElementChipHtmlResolving;
 use CraftCms\Cms\Cp\Icons;
@@ -425,12 +426,11 @@ public function elementCardHeaderHtml(ElementInterface $element, array $config =
             ($config['selectable'] ? $this->componentCheckboxHtml(sprintf('%s-label', $config['id'])) : '').
             ($showEditButton ? Button::make()
                 ->icon('edit')
+                ->appearance(Appearance::Plain)
+                ->size('small')
                 ->attributes([
-                    'class' => ['chromeless', 'small', 'edit-btn'],
+                    'class' => ['edit-btn'],
                     'id' => $editId,
-                    'title' => mb_ucfirst(t('Edit {type}', [
-                        'type' => $element::lowerDisplayName(),
-                    ])),
                     'aria' => [
                         'label' => mb_ucfirst(t('Edit {type}', [
                             'type' => $element::lowerDisplayName(),

From 4e813b65b53eb0d320eda17fa3e8ebc743b5d83a Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Mon, 27 Jul 2026 13:19:28 -0500
Subject: [PATCH 10/15] Default legacy element template vars for strict mode

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 resources/templates/_elements/sources.twig | 6 ++++++
 resources/templates/_elements/toolbar.twig | 5 +++++
 2 files changed, 11 insertions(+)

diff --git a/resources/templates/_elements/sources.twig b/resources/templates/_elements/sources.twig
index 0a47bf0ab5a..7009e05aee8 100644
--- a/resources/templates/_elements/sources.twig
+++ b/resources/templates/_elements/sources.twig
@@ -67,6 +67,12 @@
     {% endif %}
 {% endmacro %}
 
+{% set keyPrefix = keyPrefix ?? '' %}
+{# Inherited quirk: no caller has ever defined `isTopLevel` (in Craft 5 it
+   resolved to undefined→falsy), so the sourceLink() sort/table-column data
+   attributes never render. Defaulting it keeps that exact output under
+   strict variables. #}
+{% set isTopLevel = isTopLevel ?? false %}
 {% set nestedUnderHeading = false %}
 
 {% tag 'ul' with {
diff --git a/resources/templates/_elements/toolbar.twig b/resources/templates/_elements/toolbar.twig
index 820d9b5966d..88087bc7b6f 100644
--- a/resources/templates/_elements/toolbar.twig
+++ b/resources/templates/_elements/toolbar.twig
@@ -1,5 +1,10 @@
 {% from "_includes/forms" import text -%}
 
+{# Inherited quirks: no caller has ever passed `idPrefix` or
+   `isAdministrative` (in Craft 5 they resolved to undefined→empty/falsy).
+   Defaulting them keeps that exact output under strict variables. #}
+{% set idPrefix = idPrefix ?? '' %}
+{% set isAdministrative = isAdministrative ?? false %}
 
 {% hook 'cp.elements.toolbar' %}
 

From d124ab46d8cb6a5f3c7905b6284ccad057638419 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Mon, 27 Jul 2026 13:19:37 -0500
Subject: [PATCH 11/15] Support PHPStan literal types in TS transpilation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../TypeScript/ClassListClassTransformer.php  |  7 +++
 .../LiteralAwareTranspileAction.php           | 52 +++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 workbench/app/TypeScript/LiteralAwareTranspileAction.php

diff --git a/workbench/app/TypeScript/ClassListClassTransformer.php b/workbench/app/TypeScript/ClassListClassTransformer.php
index 495a050deb9..041886d49c6 100644
--- a/workbench/app/TypeScript/ClassListClassTransformer.php
+++ b/workbench/app/TypeScript/ClassListClassTransformer.php
@@ -13,6 +13,13 @@
 
 class ClassListClassTransformer extends ClassTransformer
 {
+    public function __construct()
+    {
+        parent::__construct(
+            transpilePhpStanTypeToTypeScriptTypeAction: new LiteralAwareTranspileAction,
+        );
+    }
+
     protected function shouldTransform(PhpClassNode $phpClassNode): bool
     {
         return true;
diff --git a/workbench/app/TypeScript/LiteralAwareTranspileAction.php b/workbench/app/TypeScript/LiteralAwareTranspileAction.php
new file mode 100644
index 00000000000..4d745acf589
--- /dev/null
+++ b/workbench/app/TypeScript/LiteralAwareTranspileAction.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workbench\App\TypeScript;
+
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprFalseNode;
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprFloatNode;
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprIntegerNode;
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprNullNode;
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprStringNode;
+use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprTrueNode;
+use PHPStan\PhpDocParser\Ast\Type\ConstTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\TypeNode;
+use Spatie\TypeScriptTransformer\Actions\TranspilePhpStanTypeToTypeScriptNodeAction;
+use Spatie\TypeScriptTransformer\PhpNodes\PhpClassNode;
+use Spatie\TypeScriptTransformer\TypeScriptNodes\TypeScriptLiteral;
+use Spatie\TypeScriptTransformer\TypeScriptNodes\TypeScriptNode;
+
+/**
+ * Extends the stock PHPStan-doc transpiler with literal const types: the
+ * upstream action only understands `ConstTypeNode` for enum-const generics,
+ * so scalar literals in array shapes — the discriminants of tagged unions
+ * like `array{mode: 'cards', …}|array{mode: 'index', …}` — fell through to
+ * `unknown`. Here they become TypeScript literal types.
+ */
+class LiteralAwareTranspileAction extends TranspilePhpStanTypeToTypeScriptNodeAction
+{
+    #[\Override]
+    protected function resolve(
+        TypeNode $type,
+        ?PhpClassNode $phpClassNode,
+    ): TypeScriptNode {
+        if ($type instanceof ConstTypeNode) {
+            $literal = match ($type->constExpr::class) {
+                ConstExprStringNode::class => new TypeScriptLiteral($type->constExpr->value),
+                ConstExprIntegerNode::class => new TypeScriptLiteral((int) $type->constExpr->value),
+                ConstExprFloatNode::class => new TypeScriptLiteral((float) $type->constExpr->value),
+                ConstExprTrueNode::class => new TypeScriptLiteral(true),
+                ConstExprFalseNode::class => new TypeScriptLiteral(false),
+                ConstExprNullNode::class => new TypeScriptLiteral(null),
+                default => null,
+            };
+
+            if ($literal !== null) {
+                return $literal;
+            }
+        }
+
+        return parent::resolve($type, $phpClassNode);
+    }
+}

From 66f2dac8fa24d53a5bdc934d37fb6a244ee7bd21 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Mon, 27 Jul 2026 13:20:00 -0500
Subject: [PATCH 12/15] Render account addresses from nested-element data

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../cp/src/js/CraftElementLabel.js            |   7 +
 packages/craftcms-ui/src/actions/index.ts     |  50 +-
 .../src/components/action-item/action-item.ts |  13 +-
 .../src/components/button/button.test.ts      |  88 ++++
 .../src/components/button/button.ts           |  37 ++
 .../src/components/card/card.stories.ts       | 223 +++++++-
 .../src/components/card/card.styles.ts        |   2 +
 .../src/components/card/card.test.ts          |  92 ++++
 .../craftcms-ui/src/components/card/card.ts   |  61 ++-
 .../craftcms-ui/src/components/empty/empty.ts |   2 +-
 resources/js/common/types/globals.d.ts        |   1 +
 .../nested-element-manager.ts                 |   6 +-
 resources/js/modules/slideout/index.ts        |  46 +-
 resources/js/pages/users/Addresses.vue        | 154 +++++-
 src/Cp/Components/Button.php                  |  18 +
 src/Cp/Html/ElementHtml.php                   | 181 ++++---
 src/Element/NestedElementManager.php          | 498 ++++++++++++------
 .../ViewModels/UserAddressesViewModel.php     |  94 ++++
 .../tests/account/addresses.test.js           | 198 +++++++
 .../Element/NestedElementManagerTest.php      |  99 ++++
 20 files changed, 1621 insertions(+), 249 deletions(-)
 create mode 100644 packages/craftcms-ui/src/components/card/card.test.ts
 create mode 100644 tests-playwright/tests/account/addresses.test.js

diff --git a/packages/craftcms-legacy/cp/src/js/CraftElementLabel.js b/packages/craftcms-legacy/cp/src/js/CraftElementLabel.js
index b72d09367bd..520163aaf46 100644
--- a/packages/craftcms-legacy/cp/src/js/CraftElementLabel.js
+++ b/packages/craftcms-legacy/cp/src/js/CraftElementLabel.js
@@ -56,6 +56,13 @@ class CraftElementLabel extends HTMLElement {
   }
 
   update() {
+    // Bail while the label isn't measurable (e.g. before a containing web
+    // component's first shadow render assigns its slots) — a 0-width label
+    // would always register as overflowing.
+    if (this.scrollWidth === 0) {
+      return;
+    }
+
     this.desiredWidth = this.calculateWidth(this.innerText);
     this.hasOverflow = this.desiredWidth > this.scrollWidth;
 
diff --git a/packages/craftcms-ui/src/actions/index.ts b/packages/craftcms-ui/src/actions/index.ts
index 21eba3a889e..2d49e2d3938 100644
--- a/packages/craftcms-ui/src/actions/index.ts
+++ b/packages/craftcms-ui/src/actions/index.ts
@@ -55,7 +55,47 @@ export interface ActionItemButton extends BaseActionItem {
 
 export type ActionItem = ActionItemButton | ActionItemHr | ActionItemLink;
 
-export async function runAction(action: BaseAction): Promise<void> {
+export interface RunActionOptions {
+  /**
+   * The element that invoked the action (e.g. the clicked button). For
+   * `event` actions it's merged into the dispatched event's `detail` as
+   * `trigger`, so listeners can manage focus or read contextual `data-*`
+   * attributes from the invoker's ancestors.
+   */
+  trigger?: Element;
+  /**
+   * The DOM event that invoked the action. For `event` actions it's merged
+   * into the dispatched event's `detail` as `sourceEvent`, so listeners can
+   * inspect modifier keys (e.g. ctrl-click opening a new window).
+   */
+  sourceEvent?: Event;
+}
+
+/**
+ * Normalizes an action property value to a `BaseAction`. Vue's in-DOM
+ * template compiler (e.g. server HTML rendered through `DynamicHtmlRenderer`)
+ * assigns attribute values directly to an upgraded element's property as a
+ * raw JSON string, bypassing Lit's attribute converter — so components accept
+ * both and normalize before running.
+ */
+export function normalizeAction(
+  action: BaseAction | string | null
+): BaseAction | null {
+  if (typeof action !== 'string') {
+    return action;
+  }
+
+  try {
+    return JSON.parse(action);
+  } catch {
+    return null;
+  }
+}
+
+export async function runAction(
+  action: BaseAction,
+  options: RunActionOptions = {}
+): Promise<void> {
   switch (action.type) {
     case 'clipboard':
       await navigator.clipboard.writeText(action.value);
@@ -101,7 +141,13 @@ export async function runAction(action: BaseAction): Promise<void> {
       }
 
       window.dispatchEvent(
-        new CustomEvent(action.name, {detail: action.detail ?? {}})
+        new CustomEvent(action.name, {
+          detail: {
+            ...(action.detail ?? {}),
+            ...(options.trigger ? {trigger: options.trigger} : {}),
+            ...(options.sourceEvent ? {sourceEvent: options.sourceEvent} : {}),
+          },
+        })
       );
       break;
 
diff --git a/packages/craftcms-ui/src/components/action-item/action-item.ts b/packages/craftcms-ui/src/components/action-item/action-item.ts
index 4cdc614923a..dae63b07ae1 100644
--- a/packages/craftcms-ui/src/components/action-item/action-item.ts
+++ b/packages/craftcms-ui/src/components/action-item/action-item.ts
@@ -10,6 +10,7 @@ import {
   type ActionFeedback,
   type BaseAction,
   type FeedbackData,
+  normalizeAction,
   runAction,
 } from '@src/actions';
 import {Variant, type VariantValue} from '@src/constants/variants';
@@ -43,7 +44,7 @@ export default class CraftActionItem extends LitElement {
   @property({type: Boolean}) checked: boolean = false;
   @property({type: Boolean}) active: boolean = false;
   @property() type: 'button' | 'checkbox' = 'button';
-  @property({type: Object}) action: BaseAction | null = null;
+  @property({type: Object}) action: BaseAction | string | null = null;
   @property({type: Object}) feedback: ActionFeedback | null = null;
   @property({type: Number, attribute: 'feedback-duration'})
   feedbackDuration: number = 1000;
@@ -115,7 +116,7 @@ export default class CraftActionItem extends LitElement {
         composed: true,
         detail: {
           state,
-          actionType: this.action?.type,
+          actionType: normalizeAction(this.action)?.type,
           ...detail,
         },
       })
@@ -128,14 +129,16 @@ export default class CraftActionItem extends LitElement {
       return;
     }
 
-    if (event.type === 'click' && this.action) {
+    const action = normalizeAction(this.action);
+
+    if (event.type === 'click' && action) {
       // Only show loading spinner for http requests
-      if (this.action.type === 'http') {
+      if (action.type === 'http') {
         this.setState(AsyncStates.Loading);
       }
 
       try {
-        await runAction(this.action);
+        await runAction(action, {trigger: this, sourceEvent: event});
         this.setState(AsyncStates.Success, this.feedback?.success);
       } catch (error: any) {
         this.setState(AsyncStates.Error, {
diff --git a/packages/craftcms-ui/src/components/button/button.test.ts b/packages/craftcms-ui/src/components/button/button.test.ts
index 83c66ed4e2f..52982bc9238 100644
--- a/packages/craftcms-ui/src/components/button/button.test.ts
+++ b/packages/craftcms-ui/src/components/button/button.test.ts
@@ -158,3 +158,91 @@ describe('craft-button link semantics', () => {
     expect(element.tabIndex).toBe(0);
   });
 });
+
+describe('craft-button actions', () => {
+  it('parses a JSON action attribute into the action property', async () => {
+    const element = await createButton({
+      action: '{"type":"event","name":"craft:test"}',
+    });
+    expect(element.action).toEqual({type: 'event', name: 'craft:test'});
+  });
+
+  it('runs an event action on click, with trigger and sourceEvent in the detail', async () => {
+    const element = await createButton({
+      action:
+        '{"type":"event","name":"craft:test-action","detail":{"foo":"bar"}}',
+    });
+
+    let detail: any = null;
+    window.addEventListener(
+      'craft:test-action',
+      ((ev: CustomEvent) => {
+        detail = ev.detail;
+      }) as EventListener,
+      {once: true}
+    );
+    element.click();
+
+    expect(detail).not.toBeNull();
+    expect(detail.foo).toBe('bar');
+    expect(detail.trigger).toBe(element);
+    expect(detail.sourceEvent).toBeInstanceOf(Event);
+  });
+
+  it('runs an action assigned as a raw JSON string property (Vue in-DOM compilation)', async () => {
+    const element = await createButton();
+    element.action = '{"type":"event","name":"craft:test-string"}';
+
+    let fired = false;
+    window.addEventListener(
+      'craft:test-string',
+      () => {
+        fired = true;
+      },
+      {once: true}
+    );
+    element.click();
+
+    expect(fired).toBe(true);
+  });
+
+  it('does not run the action when disabled', async () => {
+    const element = await createButton({
+      action: '{"type":"event","name":"craft:test-disabled"}',
+      disabled: '',
+    });
+
+    let fired = false;
+    window.addEventListener(
+      'craft:test-disabled',
+      () => {
+        fired = true;
+      },
+      {once: true}
+    );
+    element.click();
+
+    expect(fired).toBe(false);
+  });
+
+  it('stops running the action once it is removed', async () => {
+    const element = await createButton({
+      action: '{"type":"event","name":"craft:test-removed"}',
+    });
+    element.removeAttribute('action');
+    element.action = null;
+    await element.updateComplete;
+
+    let fired = false;
+    window.addEventListener(
+      'craft:test-removed',
+      () => {
+        fired = true;
+      },
+      {once: true}
+    );
+    element.click();
+
+    expect(fired).toBe(false);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/button/button.ts b/packages/craftcms-ui/src/components/button/button.ts
index 856d022a2eb..a96491d3249 100644
--- a/packages/craftcms-ui/src/components/button/button.ts
+++ b/packages/craftcms-ui/src/components/button/button.ts
@@ -7,6 +7,7 @@ import '../icon/icon.js';
 import {computeAccessibleName} from 'dom-accessibility-api';
 import {classMap} from 'lit/directives/class-map.js';
 import variantsStyles from '@src/styles/variants.styles';
+import {type BaseAction, normalizeAction, runAction} from '@src/actions';
 
 export const ButtonAppearance = {
   Solid: 'solid',
@@ -56,8 +57,35 @@ export default class CraftButton extends LionButtonSubmit {
     }
     super.connectedCallback();
     this.syncLinkHostState();
+    this.addEventListener('click', this.#handleActionClick);
   }
 
+  override disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener('click', this.#handleActionClick);
+  }
+
+  #handleActionClick = async (event: Event) => {
+    const action = normalizeAction(this.action);
+
+    if (!action || this.disabled) {
+      return;
+    }
+
+    event.preventDefault();
+
+    // Only show the spinner for http requests, matching craft-action-item.
+    if (action.type === 'http') {
+      this.loading = true;
+    }
+
+    try {
+      await runAction(action, {trigger: this, sourceEvent: event});
+    } finally {
+      this.loading = false;
+    }
+  };
+
   override updated(changedProperties: Map<string, unknown>) {
     super.updated(changedProperties);
     if (changedProperties.has('href') || changedProperties.has('disabled')) {
@@ -140,6 +168,15 @@ export default class CraftButton extends LionButtonSubmit {
   /** Icon to be rendered within the content. */
   @property() icon: string | null = null;
 
+  /**
+   * Declarative action to run when the button is clicked, as a JSON `action`
+   * attribute — the same primitives `craft-action-item` supports
+   * (`http`/`event`/`clipboard`/`download`, run via `runAction()`). A raw
+   * JSON string is accepted too (Vue's in-DOM compiler sets attribute
+   * values as string properties on upgraded elements).
+   */
+  @property({type: Object}) action: BaseAction | string | null = null;
+
   /** When set, the button renders as a link to this URL. */
   @property({reflect: true}) href: string | null = null;
 
diff --git a/packages/craftcms-ui/src/components/card/card.stories.ts b/packages/craftcms-ui/src/components/card/card.stories.ts
index e6cbc5af65a..181ace4c982 100644
--- a/packages/craftcms-ui/src/components/card/card.stories.ts
+++ b/packages/craftcms-ui/src/components/card/card.stories.ts
@@ -2,25 +2,232 @@ import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
 
+import type CraftCard from './card.js';
 import './card.js';
+import '../button/button.js';
+import '../icon/icon.js';
+
+const placeholderThumb = html`
+  <svg
+    slot="thumbnail"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 120 120"
+    role="img"
+    aria-label="Placeholder thumbnail"
+    style="display: block; width: 100%; height: auto; border-radius: 4px;"
+  >
+    <rect width="120" height="120" fill="#e2e8f0" />
+    <path d="M20 88l24-28 18 20 14-16 24 24v12H20z" fill="#94a3b8" />
+    <circle cx="42" cy="38" r="10" fill="#94a3b8" />
+  </svg>
+`;
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Card',
   component: 'craft-card',
-  argTypes: {},
-  render: (args) => html`
-    <craft-card>
-      Cards are really pretty boring, their mostly available as a convienience
-      for layout.
+  args: {
+    label: 'Card label',
+    active: false,
+    thumbAlignment: 'start',
+  },
+  argTypes: {
+    label: {
+      control: {type: 'text'},
+      description:
+        'Header label; the header only renders when this (or a header/label/actions slot) is present',
+    },
+    active: {
+      control: {type: 'boolean'},
+    },
+    thumbAlignment: {
+      control: {type: 'select'},
+      options: ['start', 'end'],
+    },
+  },
+  render: ({label, active}) => html`
+    <craft-card label="${label}" ?active="${active}">
+      Cards group related content into a bordered surface, with optional header,
+      footer, and thumbnail regions.
     </craft-card>
   `,
-} satisfies Meta<any>;
+} satisfies Meta<CraftCard>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftCard>;
 
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+
+/** Body only — with no label or header/label/actions slot, no header renders. */
 export const Default: Story = {
-  args: {},
+  render: () => html`
+    <craft-card>
+      A bare card is just the bordered body surface — no header or footer chrome
+      until content asks for it.
+    </craft-card>
+  `,
+};
+
+/** The `label` attribute alone brings in the header region. */
+export const WithLabel: Story = {};
+
+/** Buttons in the `actions` slot sit at the end of the header. */
+export const WithActions: Story = {
+  render: ({label}) => html`
+    <craft-card label="${label}">
+      <craft-button
+        slot="actions"
+        icon="pencil"
+        appearance="plain"
+        size="small"
+        aria-label="Edit"
+      ></craft-button>
+      <craft-button
+        slot="actions"
+        icon="ellipsis"
+        appearance="plain"
+        size="small"
+        aria-label="Actions"
+      ></craft-button>
+
+      Header actions are slotted content, so anything works — icon buttons, an
+      action menu, a switch.
+    </craft-card>
+  `,
+};
+
+/** The `label` slot replaces the label text while keeping the header layout. */
+export const CustomLabel: Story = {
+  render: () => html`
+    <craft-card>
+      <span
+        slot="label"
+        style="display: inline-flex; align-items: center; gap: 0.5em;"
+      >
+        <craft-icon name="newspaper"></craft-icon>
+        Article
+        <code>article</code>
+      </span>
+
+      A slotted label can carry richer content than plain text — icons, handles,
+      badges.
+    </craft-card>
+  `,
+};
+
+/** The `header` slot replaces the whole default label/actions header. */
+export const CustomHeader: Story = {
+  render: () => html`
+    <craft-card>
+      <div
+        slot="header"
+        style="display: flex; align-items: center; justify-content: space-between; inline-size: 100%;"
+      >
+        <strong>Custom header</strong>
+        <em>anything goes here</em>
+      </div>
+
+      When the header slot is filled, the default label/actions layout is
+      replaced entirely.
+    </craft-card>
+  `,
+};
+
+/** The footer region only renders when the `footer` slot is filled. */
+export const WithFooter: Story = {
+  render: ({label}) => html`
+    <craft-card label="${label}">
+      Body content.
+
+      <div
+        slot="footer"
+        style="display: flex; justify-content: space-between; inline-size: 100%;"
+      >
+        <span>Updated 2 hours ago</span>
+        <span>Draft</span>
+      </div>
+    </craft-card>
+  `,
+};
+
+/** Thumbnail content renders in a fixed-width column beside the body. */
+export const WithThumbnail: Story = {
+  render: ({label, thumbAlignment}) => html`
+    <craft-card label="${label}" thumb-alignment="${thumbAlignment}">
+      ${placeholderThumb} The thumbnail slot gets a 120px column;
+      <code>thumb-alignment</code> puts it at the start or end of the body.
+    </craft-card>
+  `,
+};
+
+export const ThumbnailAlignment: Story = {
+  render: () => html`
+    <div style="display: grid; gap: 1rem;">
+      <craft-card label='thumb-alignment="start"'>
+        ${placeholderThumb} Thumbnail leading the body content.
+      </craft-card>
+      <craft-card label='thumb-alignment="end"' thumb-alignment="end">
+        ${placeholderThumb} Thumbnail trailing the body content.
+      </craft-card>
+    </div>
+  `,
+};
+
+/** The reflected `active` attribute marks selection (e.g. element index rows). */
+export const Active: Story = {
+  render: ({label}) => html`
+    <div style="display: grid; gap: 1rem;">
+      <craft-card label="${label}">An inactive card for comparison.</craft-card>
+      <craft-card label="${label}" active>
+        An active card — loud header/footer fill and border.
+      </craft-card>
+    </div>
+  `,
+};
+
+/** Radius, shadow, and padding are themeable via custom properties. */
+export const CustomProperties: Story = {
+  render: ({label}) => html`
+    <craft-card
+      label="${label}"
+      style="--c-card-radius: 0; --c-card-shadow: none; --c-card-padding-inline: 2rem; --c-card-padding-block: 1rem;"
+    >
+      Square corners, no shadow, and roomier padding via
+      <code>--c-card-*</code> custom properties.
+    </craft-card>
+  `,
+};
+
+export const KitchenSink: Story = {
+  render: ({label, active, thumbAlignment}) => html`
+    <craft-card
+      label="${label}"
+      ?active="${active}"
+      thumb-alignment="${thumbAlignment}"
+    >
+      <craft-button
+        slot="actions"
+        icon="ellipsis"
+        appearance="plain"
+        size="small"
+        aria-label="Actions"
+      ></craft-button>
+
+      ${placeholderThumb}
+
+      <strong>Autumn on the Coast</strong>
+      <p style="margin: 0.25em 0 0">
+        Header label and actions, a leading thumbnail, body content, and a
+        metadata footer — all regions at once.
+      </p>
+
+      <div
+        slot="footer"
+        style="display: flex; justify-content: space-between; inline-size: 100%;"
+      >
+        <span>Posted Oct 14</span>
+        <span>Live</span>
+      </div>
+    </craft-card>
+  `,
 };
diff --git a/packages/craftcms-ui/src/components/card/card.styles.ts b/packages/craftcms-ui/src/components/card/card.styles.ts
index ccb39632bf8..97c0abd4712 100644
--- a/packages/craftcms-ui/src/components/card/card.styles.ts
+++ b/packages/craftcms-ui/src/components/card/card.styles.ts
@@ -29,6 +29,7 @@ export default css`
     border-radius: var(--c-card-radius, var(--c-radius-md));
     box-shadow: var(--c-card-shadow, var(--c-shadow-sm));
     position: relative;
+    height: 100%;
   }
 
   .card__header,
@@ -62,6 +63,7 @@ export default css`
   .card__actions {
     display: flex;
     gap: var(--c-spacing-sm);
+    align-self: end;
   }
 
   .card-body {
diff --git a/packages/craftcms-ui/src/components/card/card.test.ts b/packages/craftcms-ui/src/components/card/card.test.ts
new file mode 100644
index 00000000000..78ae9602d8d
--- /dev/null
+++ b/packages/craftcms-ui/src/components/card/card.test.ts
@@ -0,0 +1,92 @@
+import {beforeEach, describe, expect, it} from 'vitest';
+import type CraftCard from './card.js';
+import './card.js';
+
+async function createCard(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Body'
+): Promise<CraftCard> {
+  const element = document.createElement('craft-card') as CraftCard;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function shadow(element: CraftCard, selector: string): HTMLElement | null {
+  return element.shadowRoot?.querySelector(selector) ?? null;
+}
+
+/**
+ * Settle the light-DOM MutationObserver / `slotchange` dispatch and the
+ * re-render they queue.
+ */
+async function settle(element: CraftCard): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve));
+  await element.updateComplete;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-card header/footer presence', () => {
+  it('renders no header or footer chrome for a bare body', async () => {
+    const element = await createCard();
+
+    expect(shadow(element, '.card__header')).toBeNull();
+    expect(shadow(element, '.card__footer')).toBeNull();
+  });
+
+  it('renders the header for slotted label/actions content', async () => {
+    const element = await createCard({}, '<span slot="label">Label</span>Body');
+    await settle(element);
+
+    expect(shadow(element, '.card__header')).not.toBeNull();
+  });
+
+  it('tracks header and footer content added after first render', async () => {
+    const element = await createCard();
+    expect(shadow(element, '.card__footer')).toBeNull();
+
+    const footer = document.createElement('div');
+    footer.slot = 'footer';
+    footer.textContent = 'Meta';
+    element.append(footer);
+    await settle(element);
+
+    expect(shadow(element, '.card__footer')).not.toBeNull();
+
+    footer.remove();
+    await settle(element);
+
+    expect(shadow(element, '.card__footer')).toBeNull();
+  });
+});
+
+describe('craft-card thumbnail', () => {
+  const thumb = '<img slot="thumbnail" src="data:," alt="">Body';
+
+  it('applies the thumbnail grid when thumbnail content is slotted', async () => {
+    const element = await createCard({'thumb-alignment': 'end'}, thumb);
+    await settle(element);
+
+    expect(shadow(element, '.card--has-thumbnail')).not.toBeNull();
+    expect(shadow(element, '.card-body--thumb-end')).not.toBeNull();
+  });
+
+  it('suppresses the thumbnail region when show-thumb is false', async () => {
+    const element = await createCard({}, thumb);
+    await settle(element);
+    expect(shadow(element, '.card--has-thumbnail')).not.toBeNull();
+
+    element.showThumb = false;
+    await element.updateComplete;
+
+    expect(shadow(element, '.card--has-thumbnail')).toBeNull();
+    expect(shadow(element, '.card-body__thumb')!.hidden).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/card/card.ts b/packages/craftcms-ui/src/components/card/card.ts
index 8b0d9bd1e35..06587130569 100644
--- a/packages/craftcms-ui/src/components/card/card.ts
+++ b/packages/craftcms-ui/src/components/card/card.ts
@@ -54,7 +54,8 @@ export default class CraftCard extends LitElement {
   @property({type: Boolean, reflect: true})
   active = false;
 
-  @property({attribute: 'show-thumb'}) showThumb: boolean = true;
+  /** Whether the thumbnail region renders at all, even with slotted content. */
+  @property({attribute: 'show-thumb', type: Boolean}) showThumb: boolean = true;
 
   @property({attribute: 'thumb-alignment'}) thumbAlignment: 'start' | 'end' =
     'start';
@@ -67,24 +68,60 @@ export default class CraftCard extends LitElement {
    */
   @state() private _hasThumbnail = false;
 
+  /**
+   * Whether header/footer content is currently slotted. The header and footer
+   * slots only render when filled, so (unlike the always-rendered thumbnail
+   * slot) their presence can't be tracked via `slotchange` — a light-DOM
+   * observer keeps them fresh when a consumer swaps slotted content.
+   */
+  @state() private _hasSlottedHeader = false;
+
+  @state() private _hasSlottedFooter = false;
+
+  private _lightDomObserver = new MutationObserver(() =>
+    this._syncSlotPresence()
+  );
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this._syncSlotPresence();
+    this._lightDomObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['slot'],
+    });
+  }
+
+  override disconnectedCallback() {
+    super.disconnectedCallback();
+    this._lightDomObserver.disconnect();
+  }
+
+  private _syncSlotPresence() {
+    this._hasSlottedHeader =
+      !!this.querySelector('[slot="header"]') ||
+      !!this.querySelector('[slot="label"]') ||
+      !!this.querySelector('[slot="actions"]');
+    this._hasSlottedFooter = !!this.querySelector('[slot="footer"]');
+    this._hasThumbnail = !!this.querySelector('[slot="thumbnail"]');
+  }
+
   private _handleThumbnailSlotChange(event: Event) {
     const slot = event.target as HTMLSlotElement;
     this._hasThumbnail = slot.assignedElements({flatten: true}).length > 0;
   }
 
   override render() {
-    const hasSlottedHeader =
-      !!this.label ||
-      !!this.querySelector('[slot="header"]') ||
-      !!this.querySelector('[slot="label"]') ||
-      !!this.querySelector('[slot="actions"]');
-    const hasSlottedFooter = !!this.querySelector('[slot="footer"]');
+    const hasSlottedHeader = !!this.label || this._hasSlottedHeader;
+    const hasSlottedFooter = this._hasSlottedFooter;
+    const showThumbnail = this.showThumb && this._hasThumbnail;
 
     return html`
       <div
         class="${classMap({
           card: true,
-          'card--has-thumbnail': this._hasThumbnail,
+          'card--has-thumbnail': showThumbnail,
         })}"
       >
         ${hasSlottedHeader
@@ -93,7 +130,7 @@ export default class CraftCard extends LitElement {
                 <slot name="label" class="card__label" part="label"
                   >${this.label}</slot
                 >
-                <slot name="actions"></slot>
+                <slot name="actions" class="card__actions"></slot>
               </slot>
             </div>`
           : nothing}
@@ -102,12 +139,12 @@ export default class CraftCard extends LitElement {
           class="${classMap({
             'card-body': true,
             'card-body--thumb-start':
-              this._hasThumbnail && this.thumbAlignment === 'start',
+              showThumbnail && this.thumbAlignment === 'start',
             'card-body--thumb-end':
-              this._hasThumbnail && this.thumbAlignment === 'end',
+              showThumbnail && this.thumbAlignment === 'end',
           })}"
         >
-          <div class="card-body__thumb">
+          <div class="card-body__thumb" ?hidden="${!showThumbnail}">
             <slot
               name="thumbnail"
               @slotchange="${this._handleThumbnailSlotChange}"
diff --git a/packages/craftcms-ui/src/components/empty/empty.ts b/packages/craftcms-ui/src/components/empty/empty.ts
index 571b4ef772e..352ec9eb578 100644
--- a/packages/craftcms-ui/src/components/empty/empty.ts
+++ b/packages/craftcms-ui/src/components/empty/empty.ts
@@ -17,7 +17,7 @@ export default class CraftEmpty extends LitElement {
       }
 
       .cp-empty__content {
-        display: grid; 
+        display: grid;
         gap: var(--c-spacing-md);
         justify-items: center;
         max-width: 60ch;
diff --git a/resources/js/common/types/globals.d.ts b/resources/js/common/types/globals.d.ts
index 2b2ceef0a65..590c3b4a86f 100644
--- a/resources/js/common/types/globals.d.ts
+++ b/resources/js/common/types/globals.d.ts
@@ -168,6 +168,7 @@ interface CraftStatic {
   CpScreenSlideout: {
     new (url: string, settings?: object): SlideoutInstance;
   };
+  createElementEditor(elementType: string, settings?: object): SlideoutInstance;
   CustomizeSourcesModal: new (
     elementIndex: unknown,
     settings?: object
diff --git a/resources/js/modules/nested-element-manager/nested-element-manager.ts b/resources/js/modules/nested-element-manager/nested-element-manager.ts
index 8c4401bf4aa..42002ae31ad 100644
--- a/resources/js/modules/nested-element-manager/nested-element-manager.ts
+++ b/resources/js/modules/nested-element-manager/nested-element-manager.ts
@@ -1085,7 +1085,11 @@ export class NestedElementManager extends Base<NestedElementManagerSettings> {
         // "Edit" button
         const $editBtn = $element.find('.edit-btn');
         if ($editBtn.length) {
-          // Override the default event listener
+          // Strip the button's default `craft:edit-element` action — the
+          // manager opens the editor itself, with nested-draft handling the
+          // generic listener doesn't have.
+          $editBtn.removeAttr('action');
+          ($editBtn[0] as any).action = null;
           $editBtn.off('activate');
           $editBtn.on('activate', (ev: any) => {
             // focus on the button so that when the slideout is closed, it's returned to the button
diff --git a/resources/js/modules/slideout/index.ts b/resources/js/modules/slideout/index.ts
index e44be26328e..b24260369d7 100644
--- a/resources/js/modules/slideout/index.ts
+++ b/resources/js/modules/slideout/index.ts
@@ -1,4 +1,4 @@
-import {Garnish, HUD} from '@craftcms/garnish';
+import {Garnish, HUD, isCtrlKeyPressed} from '@craftcms/garnish';
 import {compatify} from '@craftcms/garnish/compat';
 import {Slideout, type SlideoutSettings} from './slideout';
 import {
@@ -64,6 +64,50 @@ Object.assign(CompatElementEditorSlideout, {
 
 craft.ElementEditorSlideout = CompatElementEditorSlideout;
 
+// `craft:edit-element` — the action-system event carried by element edit
+// buttons (see `ElementHtml::cardEditButtonConfig()`). Opens an element
+// editor slideout for the element, or its edit page in a new window on
+// ctrl-click. Contexts that need richer editor wiring (e.g. the nested
+// element manager's draft handling) strip the button's `action` and attach
+// their own behavior instead.
+window.addEventListener('craft:edit-element', ((ev: CustomEvent) => {
+  const {elementType, settings, cpEditUrl, trigger, sourceEvent} =
+    ev.detail ?? {};
+
+  if (cpEditUrl && sourceEvent && isCtrlKeyPressed(sourceEvent)) {
+    window.open(cpEditUrl);
+    return;
+  }
+
+  // Focus the trigger so that when the slideout is closed, focus is
+  // returned to it.
+  (trigger as HTMLElement | undefined)?.focus();
+
+  const editorSettings = {...(settings ?? {}), elementType};
+  // If the settings have a draftId but the (possibly since-replaced) card no
+  // longer has a `data-draft-id` attribute, drop it so the editor retrieves
+  // the current element.
+  if (
+    editorSettings.draftId &&
+    trigger instanceof Element &&
+    !trigger.closest('[data-draft-id]')
+  ) {
+    delete editorSettings.draftId;
+  }
+
+  const slideout = new ElementEditorSlideout(null, editorSettings);
+
+  // Re-announce saves as a window event, so hosts that render element data
+  // themselves (e.g. Inertia pages) can refresh it.
+  slideout.on('submit', (submitEv: any) => {
+    window.dispatchEvent(
+      new CustomEvent('craft:element-saved', {
+        detail: {element: submitEv?.response?.data?.element ?? null},
+      })
+    );
+  });
+}) as EventListener);
+
 // Reposition any open HUDs whenever a slideout opens or closes. Registered
 // against the modern `Slideout` class: the class-event dispatch is an
 // `instanceof` check, and `compatify()`/`.extend()` build real subclasses,
diff --git a/resources/js/pages/users/Addresses.vue b/resources/js/pages/users/Addresses.vue
index 0f8eccc6db1..950a4dadb46 100644
--- a/resources/js/pages/users/Addresses.vue
+++ b/resources/js/pages/users/Addresses.vue
@@ -1,9 +1,10 @@
 <script setup lang="ts">
-  import {usePage} from '@inertiajs/vue3';
-  import {t} from '@craftcms/ui';
-  import HtmlFragmentRenderer from '@/common/components/HtmlFragmentRenderer.vue';
+  import {computed, onBeforeUnmount, onMounted, ref} from 'vue';
+  import {router, usePage} from '@inertiajs/vue3';
+  import {attrs, t} from '@craftcms/ui';
   import LayoutSlot from '@/common/components/LayoutSlot.vue';
   import Pane from '@/common/components/Pane.vue';
+  import DynamicHtmlRenderer from '@/common/components/DynamicHtmlRenderer.vue';
 
   defineOptions({
     inheritAttrs: false,
@@ -14,14 +15,143 @@
       details?: string | null;
     };
 
-  const props = usePage<UserAddressesPageProps>().props;
+  // Read props through the page object (not a captured `page.props`
+  // reference) so partial reloads — which replace `page.props` wholesale —
+  // stay reactive.
+  const page = usePage<UserAddressesPageProps>();
+  const props = computed(() => page.props);
+
+  // `data` is a mode-discriminated union; only cards mode carries `elements`.
+  const cardsData = computed(() =>
+    page.props.data.mode === 'cards' ? page.props.data : null
+  );
+
+  const createBtn = ref<HTMLElement | null>(null);
+  const creating = ref(false);
+
+  // Mirrors the legacy manager's `canCreate()`: permission, plus room under
+  // `maxElements`.
+  const canCreateMore = computed(() => {
+    const data = cardsData.value;
+
+    if (!data?.canCreate) {
+      return false;
+    }
+
+    return !data.maxElements || data.elements.length < data.maxElements;
+  });
+
+  /**
+   * The legacy `NestedElementManager.createElement()` flow: create a fresh
+   * nested element via `elements/create`, edit it in an element editor
+   * slideout, and refresh the cards once it's saved.
+   */
+  const createNestedElement = async () => {
+    const data = cardsData.value;
+
+    if (!data || creating.value || !canCreateMore.value) {
+      return;
+    }
+
+    creating.value = true;
+
+    try {
+      const {data: response} = await Craft.sendActionRequest(
+        'POST',
+        'elements/create',
+        {
+          data: {
+            elementType: data.elementType,
+            ownerId: data.ownerId,
+            fieldId: data.fieldId,
+            siteId: data.ownerSiteId,
+            // Grouped create attributes (arrays) drive a disclosure menu in
+            // the legacy manager; only a plain attributes object applies here.
+            ...(typeof data.createAttributes === 'object' &&
+            data.createAttributes !== null &&
+            !Array.isArray(data.createAttributes)
+              ? data.createAttributes
+              : {}),
+          },
+        }
+      );
+
+      const slideout = Craft.createElementEditor(data.elementType, {
+        siteId: response.element.siteId,
+        elementId: response.element.id,
+        draftId: response.element.draftId,
+        params: {fresh: 1},
+      });
+
+      slideout.on('submit', () => {
+        router.reload({only: ['data']});
+      });
+
+      slideout.on('close', () => {
+        createBtn.value?.focus();
+      });
+    } catch (error) {
+      Craft.cp?.displayError?.(
+        (error as {response?: {data?: {message?: string}}})?.response?.data
+          ?.message
+      );
+    } finally {
+      creating.value = false;
+    }
+  };
+
+  // Refresh the cards when an editor slideout saves an element.
+  const onElementSaved = () => {
+    router.reload({only: ['data']});
+  };
+
+  onMounted(() => {
+    window.addEventListener('craft:element-saved', onElementSaved);
+  });
+
+  onBeforeUnmount(() => {
+    window.removeEventListener('craft:element-saved', onElementSaved);
+  });
 </script>
 
 <template>
   <Pane appearance="raised">
     <div class="grid gap-3">
       <h2 v-if="!props.showIndex" class="text-lg m-0!">{{ t('Addresses') }}</h2>
-      <HtmlFragmentRenderer :fragment="props.contentFragment" />
+
+      <div class="card-grid">
+        <template v-for="element in cardsData?.elements" :key="element.id">
+          <craft-card
+            v-bind="attrs(element.cardAttributes, {exclude: ['class']})"
+            :thumb-alignment="element.thumbAlignment"
+          >
+            <div slot="label">
+              <DynamicHtmlRenderer :html="element.cardLabelHtml" />
+            </div>
+            <div slot="actions">
+              <DynamicHtmlRenderer :html="element.cardActionsHtml" />
+            </div>
+            <div v-if="element.cardThumbHtml" slot="thumbnail">
+              <DynamicHtmlRenderer :html="element.cardThumbHtml" />
+            </div>
+            <DynamicHtmlRenderer :html="element.cardContentHtml" />
+          </craft-card>
+        </template>
+      </div>
+
+      <div v-if="cardsData?.canCreate" class="flex">
+        <craft-button
+          ref="createBtn"
+          class="add-btn"
+          icon="plus"
+          appearance="outline"
+          :loading="creating"
+          :disabled="!canCreateMore"
+          @click="createNestedElement"
+        >
+          {{ cardsData.createButtonLabel }}
+        </craft-button>
+      </div>
     </div>
   </Pane>
 
@@ -29,3 +159,17 @@
     <div v-html="props.details"></div>
   </LayoutSlot>
 </template>
+
+<style scoped lang="scss">
+  .card-grid {
+    display: grid;
+    gap: var(--c-spacing-md);
+    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  }
+
+  /* The dashed "add" affordance the legacy `.btn.add.icon.dashed` styles gave
+     the create button. */
+  .add-btn {
+    --c-button-border-style: dashed;
+  }
+</style>
diff --git a/src/Cp/Components/Button.php b/src/Cp/Components/Button.php
index e91a07172e7..1bdf848d50d 100644
--- a/src/Cp/Components/Button.php
+++ b/src/Cp/Components/Button.php
@@ -10,6 +10,7 @@
 use CraftCms\Cms\Cp\Concerns\HasId;
 use CraftCms\Cms\Cp\Concerns\HasSize;
 use CraftCms\Cms\Cp\Concerns\HasVariant;
+use CraftCms\Cms\Support\Json;
 use Illuminate\Contracts\Support\Htmlable;
 use Illuminate\Support\HtmlString;
 use Stringable;
@@ -57,6 +58,8 @@ class Button extends ViewComponent
 
     protected string|Closure|null $iconPosition = null;
 
+    protected array|Closure|null $action = null;
+
     protected function tagName(): string
     {
         return 'craft-button';
@@ -169,6 +172,18 @@ public function iconPosition(string|Closure|null $iconPosition): static
         return $this;
     }
 
+    /**
+     * Declarative action to run on click — the same `runAction()` primitives
+     * `craft-action-item` supports (`http`/`event`/`clipboard`/`download`),
+     * serialized onto the `action` attribute.
+     */
+    public function action(array|Closure|null $action): static
+    {
+        $this->action = $action;
+
+        return $this;
+    }
+
     #[\Override]
     protected function hostAttributes(): array
     {
@@ -191,6 +206,9 @@ protected function hostAttributes(): array
             'href' => $this->evaluate($this->href),
             'target' => $this->evaluate($this->target),
             'command' => $this->evaluate($this->command),
+            'action' => ($action = $this->evaluate($this->action)) !== null
+                ? Json::encode($action, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
+                : null,
         ];
     }
 
diff --git a/src/Cp/Html/ElementHtml.php b/src/Cp/Html/ElementHtml.php
index 575ac9af212..8507300fc61 100644
--- a/src/Cp/Html/ElementHtml.php
+++ b/src/Cp/Html/ElementHtml.php
@@ -28,7 +28,6 @@
 use CraftCms\Cms\Element\NestedElementManager;
 use CraftCms\Cms\Shared\Enums\Color;
 use CraftCms\Cms\Support\Arr;
-use CraftCms\Cms\Support\Facades\HtmlStack;
 use CraftCms\Cms\Support\Facades\I18N;
 use CraftCms\Cms\Support\Facades\InputNamespace;
 use CraftCms\Cms\Support\Html;
@@ -354,11 +353,11 @@ public function elementCardHtml(ElementInterface $element, array $config = []):
 
         $attributes = $this->cardAttributes($element, $config);
 
-        $html = Html::beginTag('div', $attributes).
+        $html = Html::beginTag('craft-card', $attributes).
             $this->elementCardHeaderHtml($element, $config).
             $this->elementCardContentHtml($element, $config).
             $this->elementCardFooterHtml($element, $config).
-            Html::endTag('div'); // .card
+            Html::endTag('craft-card'); // .card
 
         event($event = new ElementCardHtmlResolving($element, $config['context'], $html));
 
@@ -374,32 +373,75 @@ public function elementCardHeaderHtml(ElementInterface $element, array $config =
     {
         $config = $this->normalizeCardConfig($element, $config);
 
-        $showEditButton = $config['showEditButton'] && Gate::check('view', $element);
+        [$showEditButton, $editAction] = $this->cardEditButtonConfig($element, $config);
+
+        return Html::beginTag('div', ['class' => 'card-titlebar']).
+            $this->elementCardLabelHtml($element, $config).
+            Html::beginTag('div', ['class' => 'card-actions-container']).
+            Html::beginTag('div', ['class' => 'card-actions']).
+            ($config['selectable'] ? $this->componentCheckboxHtml(sprintf('%s-label', $config['id'])) : '').
+            $this->cardActionsHtml($element, $config, $showEditButton, $editAction).
+            Html::endTag('div'). // .card-actions
+            Html::endTag('div'). // .card-actions-container
+            Html::endTag('div'); // .card-titlebar
+    }
+
+    /**
+     * Renders the label portion of an element’s card header: its icon, card
+     * title, and modified-status badge. Suited to a card component's `label`
+     * slot. Accepts the same `$config` settings as {@see elementCardHtml()}.
+     */
+    public function elementCardLabelHtml(ElementInterface $element, array $config = []): string
+    {
+        $icon = $element instanceof Iconic ? $element->getIcon() : null;
+        $title = $element->getCardTitle();
+
+        return Html::beginTag('div', [
+            'class' => ['flex', 'flex-nowrap', 'gap-1', 'grow-1', 'items-center'],
+        ]).
+            ($icon ? Html::tag('craft-icon', '', ['name' => $icon]) : '').
+            ($title ? Html::tag('div', Html::encode($title), ['class' => 'card-titlebar-label']) : '').
+            Html::endTag('div'). // .flex
+            $this->cardModifiedStatusHtml($element);
+    }
+
+    /**
+     * Renders the actions portion of an element’s card header — the edit
+     * button, action menu, and (when sortable) drag handle — as a plain
+     * fragment, suited to a card component's `actions` slot. Accepts the
+     * same `$config` settings as {@see elementCardHtml()}.
+     */
+    public function elementCardActionsHtml(ElementInterface $element, array $config = []): string
+    {
+        $config = $this->normalizeCardConfig($element, $config);
+
+        [$showEditButton, $editAction] = $this->cardEditButtonConfig($element, $config);
 
-        $editId = null;
-        if ($showEditButton) {
-            $editId = sprintf('action-edit-%s', mt_rand());
-            HtmlStack::jsWithVars(fn ($id, $elementType, $settings, $cpEditUrl) => <<<JS
-$('#' + $id).on('activate', (ev) => {
-  if ($cpEditUrl && Garnish.isCtrlKeyPressed(ev.originalEvent)) {
-    window.open($cpEditUrl)
-  } else {
-    // focus on the button so that when the slideout is closed, it's returned to the button
-    $(ev.currentTarget).focus();
-
-    const settings = $settings;
-    // if settings have draftId but the replaced card doesn't have the data-draft-id attribute anymore,
-    // remove the draftId from the settings before creating element editor, so the correct element can be retrieved
-    if (settings.draftId && !Garnish.hasAttr($(ev.currentTarget).parents('.card'), 'data-draft-id')) {
-      delete settings.draftId;
+        return $this->cardActionsHtml($element, $config, $showEditButton, $editAction);
     }
-    Craft.createElementEditor($elementType, settings)
-  }
-});
-JS, [
-                InputNamespace::namespaceId($editId),
-                $element::class,
-                [
+
+    /**
+     * Resolves whether the card gets an edit button and, when it does, the
+     * `craft:edit-element` event action it should run — handled by the
+     * slideout module's window listener, which opens an element editor
+     * slideout (or the element's edit page on ctrl-click).
+     *
+     * @return array{0: bool, 1: array<string, mixed>|null} `[showEditButton, editAction]`
+     */
+    private function cardEditButtonConfig(ElementInterface $element, array $config): array
+    {
+        $showEditButton = $config['showEditButton'] && Gate::check('view', $element);
+
+        if (! $showEditButton) {
+            return [false, null];
+        }
+
+        return [true, [
+            'type' => 'event',
+            'name' => 'craft:edit-element',
+            'detail' => [
+                'elementType' => $element::class,
+                'settings' => [
                     'elementId' => $element->isProvisionalDraft ? $element->getCanonicalId() : $element->id,
                     'draftId' => $element->isProvisionalDraft ? null : $element->draftId,
                     'revisionId' => $element->revisionId,
@@ -407,36 +449,25 @@ public function elementCardHeaderHtml(ElementInterface $element, array $config =
                     'ownerId' => $element instanceof NestedElementInterface ? $element->getOwnerId() : null,
                 ],
                 'cpEditUrl' => $element->getCpEditUrl(),
-            ]);
-        }
-
-        $icon = $element instanceof Iconic ? $element->getIcon() : null;
-        $title = $element->getCardTitle();
+            ],
+        ]];
+    }
 
-        return Html::beginTag('div', ['class' => 'card-titlebar']).
-            Html::beginTag('div', [
-                'class' => ['flex', 'flex-nowrap', 'gap-1', 'items-center'],
-            ]).
-            ($icon ? Html::tag('craft-icon', '', ['name' => $icon]) : '').
-            ($title ? Html::tag('div', Html::encode($title), ['class' => 'card-titlebar-label']) : '').
-            Html::endTag('div'). // .flex
-            $this->cardModifiedStatusHtml($element).
-            Html::beginTag('div', ['class' => 'card-actions-container']).
-            Html::beginTag('div', ['class' => 'card-actions']).
-            ($config['selectable'] ? $this->componentCheckboxHtml(sprintf('%s-label', $config['id'])) : '').
-            ($showEditButton ? Button::make()
-                ->icon('edit')
-                ->appearance(Appearance::Plain)
-                ->size('small')
-                ->attributes([
-                    'class' => ['edit-btn'],
-                    'id' => $editId,
-                    'aria' => [
-                        'label' => mb_ucfirst(t('Edit {type}', [
-                            'type' => $element::lowerDisplayName(),
-                        ])),
-                    ],
-                ]) : '').
+    private function cardActionsHtml(ElementInterface $element, array $config, bool $showEditButton, ?array $editAction): string
+    {
+        return ($showEditButton ? Button::make()
+            ->icon('edit')
+            ->appearance(Appearance::Plain)
+            ->size('small')
+            ->action($editAction)
+            ->attributes([
+                'class' => ['edit-btn'],
+                'aria' => [
+                    'label' => mb_ucfirst(t('Edit {type}', [
+                        'type' => $element::lowerDisplayName(),
+                    ])),
+                ],
+            ]) : '').
             ($config['showActionMenu'] ? $this->componentActionMenu($element, ! $showEditButton, $this->nestedCardActionItems($element, $config)) : '').
             ($config['sortable'] ? Button::make()
                 ->icon('move')
@@ -448,10 +479,7 @@ public function elementCardHeaderHtml(ElementInterface $element, array $config =
                     ],
                     'role' => 'none',
                     'tabindex' => '-1',
-                ]) : '').
-            Html::endTag('div'). // .card-actions
-            Html::endTag('div'). // .card-actions-container
-            Html::endTag('div'); // .card-titlebar
+                ]) : '');
     }
 
     /**
@@ -486,8 +514,15 @@ public function elementCardContentHtml(ElementInterface $element, array $config
             ($bodyContent !== '' ? Html::tag('div', $bodyContent, ['class' => 'card-body']) : '').
             Html::endTag('div'); // .card-content
 
-        $thumbHtml = $element->getThumbHtml(120);
-        $thumbAlignment = $element->getFieldLayout()?->getCardThumbAlignment() ?? 'end';
+        // Consumers that render the thumbnail themselves (e.g. a card
+        // component's `thumbnail` slot, via `elementCardThumbHtml()`) can
+        // opt out of the inline thumb.
+        if (! $config['withThumb']) {
+            return Html::beginTag('div', ['class' => 'card-main']).$contentHtml.Html::endTag('div');
+        }
+
+        $thumbHtml = $this->elementCardThumbHtml($element);
+        $thumbAlignment = $this->elementCardThumbAlignment($element);
 
         $html = Html::beginTag('div', ['class' => 'card-main']);
 
@@ -500,6 +535,27 @@ public function elementCardContentHtml(ElementInterface $element, array $config
         return $html.Html::endTag('div');
     }
 
+    /**
+     * Renders an element card’s thumbnail, suited to a card component's
+     * `thumbnail` slot (pair with {@see elementCardThumbAlignment()}).
+     */
+    public function elementCardThumbHtml(ElementInterface $element): string
+    {
+        return $element->getThumbHtml(120) ?? '';
+    }
+
+    /**
+     * The card thumbnail alignment configured by the element’s field layout.
+     *
+     * @return 'start'|'end'
+     */
+    public function elementCardThumbAlignment(ElementInterface $element): string
+    {
+        $alignment = $element->getFieldLayout()?->getCardThumbAlignment();
+
+        return $alignment === 'start' ? 'start' : 'end';
+    }
+
     /**
      * Renders the footer portion of an element’s card.
      *
@@ -554,6 +610,7 @@ private function normalizeCardConfig(ElementInterface $element, array $config):
             'showActionMenu' => false,
             'showNestedActions' => false,
             'showEditButton' => true,
+            'withThumb' => true,
             'sortable' => false,
         ];
 
diff --git a/src/Element/NestedElementManager.php b/src/Element/NestedElementManager.php
index 81b2a3f5bf7..eb5074e5337 100644
--- a/src/Element/NestedElementManager.php
+++ b/src/Element/NestedElementManager.php
@@ -277,73 +277,92 @@ private function isCustomPropagationMatch(ElementInterface $owner, int $siteId,
         return $propagationKey === self::$renderedPropagationFormats[$cacheKey];
     }
 
+    /**
+     * Returns the settings/data payload for a card grid of the nested
+     * elements — the same settings `getCardsHtml()` encodes into its
+     * `<craft-nested-element-manager settings>` attribute, plus an
+     * `elements` list of per-element card data in the shape the Vue element
+     * cards consume (`id`, `cardAttributes`, and the
+     * `cardHeaderHtml`/`cardContentHtml`/`cardFooterHtml` parts) — so a
+     * front-end (e.g. a Vue page) can render the cards itself instead of
+     * consuming server-rendered markup.
+     *
+     * Returns `null` when the owner hasn't been saved yet (the HTML method
+     * renders its "can only be created after the owner has been saved"
+     * message for that case).
+     *
+     * Grants the session authorization the nested-element endpoints require,
+     * same as the HTML path. Namespace-derived values (`baseInputName`)
+     * reflect the calling namespace context.
+     */
+    public function getCardsData(?ElementInterface $owner, array $config = []): ?array
+    {
+        if (! $owner?->id) {
+            return null;
+        }
+
+        $config = $this->normalizeViewConfig($this->normalizeCardsConfig($config));
+        $attribute = $this->viewAttribute();
+        $this->authorizeNestedElementManagement($owner, $attribute);
+
+        $settings = $this->viewSettings($owner, $config, self::VIEW_MODE_CARDS, $attribute)
+            + $this->cardsSettings($config);
+
+        // The HTML views pass the nested element type as an attribute on
+        // `<craft-nested-element-manager>`; the data path carries it in the
+        // payload (e.g. for `elements/create` requests).
+        $settings['elementType'] = $this->elementType;
+
+        $elementHtml = app(ElementHtml::class);
+        $settings['elements'] = array_map(function (ElementInterface $element) use ($elementHtml, $config): array {
+            // A per-element `id` is shared across the card parts so they line
+            // up when recomposed client-side, while staying unique per card.
+            // The thumb is provided separately (for a card component's
+            // `thumbnail` slot), so the content part omits it.
+            $cardConfig = $this->cardConfig($config) + [
+                'id' => sprintf('card-%s', mt_rand()),
+                'withThumb' => false,
+            ];
+
+            return [
+                'id' => $element->id,
+                'siteId' => $element->siteId,
+                'cardAttributes' => $elementHtml->elementCardAttributes($element, $cardConfig),
+                'cardLabelHtml' => $elementHtml->elementCardLabelHtml($element, $cardConfig),
+                'cardActionsHtml' => $elementHtml->elementCardActionsHtml($element, $cardConfig),
+                'cardContentHtml' => $elementHtml->elementCardContentHtml($element, $cardConfig),
+                'cardThumbHtml' => $elementHtml->elementCardThumbHtml($element),
+                'thumbAlignment' => $elementHtml->elementCardThumbAlignment($element),
+            ];
+        }, $this->cardElements($owner));
+
+        return $settings;
+    }
+
     public function getCardsHtml(?ElementInterface $owner, array $config = []): string
     {
-        $config += [
-            'showInGrid' => false,
-            'prevalidate' => false,
-            'selectable' => false,
-        ];
+        $config = $this->normalizeCardsConfig($config);
 
         return $this->createView(
             $owner,
             $config,
             self::VIEW_MODE_CARDS,
             function (string $id, array $config, $attribute, &$settings) use ($owner) {
-                $settings += [
-                    'deleteLabel' => mb_ucfirst(t('Delete {type}', [
-                        'type' => $this->elementType::lowerDisplayName(),
-                    ])),
-                    'deleteConfirmationMessage' => t('Are you sure you want to delete the selected {type}?', [
-                        'type' => $this->elementType::lowerDisplayName(),
-                    ]),
-                    'bulkDeleteConfirmationMessage' => t('Are you sure you want to delete the selected {type}?', [
-                        'type' => $this->elementType::pluralLowerDisplayName(),
-                    ]),
-                    'showInGrid' => $config['showInGrid'],
-                    'selectable' => $config['selectable'],
-                ];
+                $settings += $this->cardsSettings($config);
 
                 $html = Html::beginTag('div', options: [
                     'id' => $id,
                     'class' => 'nested-element-cards grid gap-2',
                 ]);
 
-                $value = $this->getValue($owner, true);
-                if ($value instanceof ElementCollection) {
-                    /** @var NestedElementInterface[] $elements */
-                    $elements = $value->all();
-                } else {
-                    /** @var NestedElementInterface[] $elements */
-                    $elements = $value->getResultOverride() ?? $value
-                        ->status(null)
-                        ->limit(null)
-                        ->all();
-                }
-
-                app(Drafts::class)->loadProvisionalChanges($elements);
-
-                if ($this->hasErrors($owner)) {
-                    foreach ($elements as $element) {
-                        if ($element->enabled && $element->getEnabledForSite()) {
-                            $element->ruleset->useScenario(ElementRules::SCENARIO_LIVE);
-                        }
-                        $element->validate();
-                    }
-                }
-
-                $this->setOwnerOnNestedElements($owner, $elements);
+                $elements = $this->cardElements($owner);
 
                 if (! empty($elements)) {
                     $html .= Html::ul()->items(...array_map(
-                        fn (ElementInterface $element) => Html::li(app(ElementHtml::class)->elementCardHtml($element, [
-                            'context' => 'field',
-                            'showActionMenu' => true,
-                            'showNestedActions' => true,
-                            'selectable' => $config['selectable'],
-                            'sortable' => $config['sortable'],
-                            'showInGrid' => $config['showInGrid'] ?? false,
-                        ]))->encode(false),
+                        fn (ElementInterface $element) => Html::li(app(ElementHtml::class)->elementCardHtml(
+                            $element,
+                            $this->cardConfig($config),
+                        ))->encode(false),
                         $elements,
                     ))->class(
                         'elements',
@@ -363,7 +382,156 @@ function (string $id, array $config, $attribute, &$settings) use ($owner) {
         );
     }
 
+    /**
+     * Applies the cards-view config defaults (shared by `getCardsHtml()` and
+     * `getCardsData()`).
+     */
+    private function normalizeCardsConfig(array $config): array
+    {
+        return $config + [
+            'showInGrid' => false,
+            'prevalidate' => false,
+            'selectable' => false,
+        ];
+    }
+
+    /**
+     * The cards-mode additions to the manager settings payload.
+     */
+    private function cardsSettings(array $config): array
+    {
+        return [
+            'deleteLabel' => mb_ucfirst(t('Delete {type}', [
+                'type' => $this->elementType::lowerDisplayName(),
+            ])),
+            'deleteConfirmationMessage' => t('Are you sure you want to delete the selected {type}?', [
+                'type' => $this->elementType::lowerDisplayName(),
+            ]),
+            'bulkDeleteConfirmationMessage' => t('Are you sure you want to delete the selected {type}?', [
+                'type' => $this->elementType::pluralLowerDisplayName(),
+            ]),
+            'showInGrid' => $config['showInGrid'],
+            'selectable' => $config['selectable'],
+        ];
+    }
+
+    /**
+     * The per-card render config for the nested context.
+     */
+    private function cardConfig(array $config): array
+    {
+        return [
+            'context' => 'field',
+            'showActionMenu' => true,
+            'showNestedActions' => true,
+            'selectable' => $config['selectable'],
+            'sortable' => $config['sortable'],
+            'showInGrid' => $config['showInGrid'] ?? false,
+        ];
+    }
+
+    /**
+     * Fetches the owner's nested elements ready for card rendering:
+     * provisional changes loaded, validated when the owner has errors, and
+     * with their owner set.
+     *
+     * @return NestedElementInterface[]
+     */
+    private function cardElements(ElementInterface $owner): array
+    {
+        $value = $this->getValue($owner, true);
+        if ($value instanceof ElementCollection) {
+            /** @var NestedElementInterface[] $elements */
+            $elements = $value->all();
+        } else {
+            /** @var NestedElementInterface[] $elements */
+            $elements = $value->getResultOverride() ?? $value
+                ->status(null)
+                ->limit(null)
+                ->all();
+        }
+
+        app(Drafts::class)->loadProvisionalChanges($elements);
+
+        if ($this->hasErrors($owner)) {
+            foreach ($elements as $element) {
+                if ($element->enabled && $element->getEnabledForSite()) {
+                    $element->ruleset->useScenario(ElementRules::SCENARIO_LIVE);
+                }
+                $element->validate();
+            }
+        }
+
+        $this->setOwnerOnNestedElements($owner, $elements);
+
+        return $elements;
+    }
+
+    /**
+     * Returns the settings/data payload for an embedded index of the nested
+     * elements — the same payload `getIndexHtml()` encodes into its
+     * `<craft-nested-element-manager settings>` attribute — so a front-end
+     * (e.g. a Vue page) can render the index itself instead of consuming
+     * server-rendered markup.
+     *
+     * Returns `null` when the owner hasn't been saved yet (the HTML method
+     * renders its "can only be created after the owner has been saved"
+     * message for that case).
+     *
+     * Grants the session authorization the nested-element endpoints require,
+     * same as the HTML path. Namespace-derived values (`baseInputName`,
+     * `indexSettings.namespace`) reflect the calling namespace context.
+     */
+    public function getIndexData(?ElementInterface $owner, array $config = []): ?array
+    {
+        if (! $owner?->id) {
+            return null;
+        }
+
+        $config = $this->normalizeViewConfig($this->normalizeIndexConfig($owner, $config));
+        $attribute = $this->viewAttribute();
+        $this->authorizeNestedElementManagement($owner, $attribute);
+
+        $settings = $this->viewSettings($owner, $config, self::VIEW_MODE_INDEX, $attribute);
+        $settings['elementType'] = $this->elementType;
+        $settings['indexSettings'] = $this->indexSettings($owner, $config, $attribute);
+
+        return $settings;
+    }
+
     public function getIndexHtml(?ElementInterface $owner, array $config = []): string
+    {
+        $config = $this->normalizeIndexConfig($owner, $config);
+
+        return $this->createView(
+            $owner,
+            $config,
+            self::VIEW_MODE_INDEX,
+            function (string $id, array $config, string $attribute, array &$settings) use ($owner): string {
+                $settings['indexSettings'] = $this->indexSettings($owner, $config, $attribute);
+
+                return app(ElementIndexHtml::class)->html($this->elementType, [
+                    'class' => [$config['prevalidate'] ? 'prevalidate' : ''],
+                    'context' => 'embedded-index',
+                    'defaultSort' => $config['defaultSort'],
+                    'defaultTableColumns' => $config['defaultTableColumns'],
+                    'defaultViewMode' => $config['defaultViewMode'],
+                    'fieldLayouts' => $config['fieldLayouts'],
+                    'id' => $id,
+                    'prevalidate' => $config['prevalidate'] ?? false,
+                    'registerJs' => false,
+                    'showSiteMenu' => false,
+                    'sources' => false,
+                ]);
+            },
+        );
+    }
+
+    /**
+     * Applies the index-view config defaults (shared by `getIndexHtml()` and
+     * `getIndexData()`).
+     */
+    private function normalizeIndexConfig(?ElementInterface $owner, array $config): array
     {
         $config += [
             'allowedViewModes' => null,
@@ -392,67 +560,54 @@ public function getIndexHtml(?ElementInterface $owner, array $config = []): stri
             }
         }
 
-        return $this->createView(
-            $owner,
-            $config,
-            self::VIEW_MODE_INDEX,
-            function (string $id, array $config, string $attribute, array &$settings) use ($owner): string {
-                $criteria = [
-                    $this->ownerIdParam => $owner->id,
-                ];
+        return $config;
+    }
 
-                if ($owner->getIsRevision()) {
-                    $criteria['revisions'] = null;
-                    $criteria['trashed'] = null;
-                    $criteria['drafts'] = false;
-                }
+    /**
+     * Builds the `indexSettings` portion of the view settings: the owner
+     * criteria, view-mode/pagination options, and (when sortable) the
+     * reorder action configs.
+     */
+    private function indexSettings(ElementInterface $owner, array $config, string $attribute): array
+    {
+        $criteria = [
+            $this->ownerIdParam => $owner->id,
+        ];
 
-                $settings['indexSettings'] = [
-                    'namespace' => InputNamespace::get(),
-                    'allowedViewModes' => $config['allowedViewModes']
-                        ? array_map(fn ($mode) => Str::toString($mode), $config['allowedViewModes'])
-                        : null,
-                    'showHeaderColumn' => $config['showHeaderColumn'],
-                    'criteria' => array_merge($criteria, $this->criteria),
-                    'batchSize' => $config['pageSize'],
-                    'actions' => [],
-                    'canHaveDrafts' => $config['canHaveDrafts'] ?? $this->elementType::hasDrafts(),
-                    'storageKey' => $config['storageKey'],
-                    'static' => $config['static'],
-                ];
+        if ($owner->getIsRevision()) {
+            $criteria['revisions'] = null;
+            $criteria['trashed'] = null;
+            $criteria['drafts'] = false;
+        }
 
-                if (! $config['static'] && $config['sortable']) {
-                    HtmlStack::startJsBuffer();
-                    $actionConfig = ElementHelper::actionConfig(new ChangeSortOrder($owner, $attribute));
-                    $actionConfig['bodyHtml'] = HtmlStack::clearJsBuffer();
-                    $settings['indexSettings']['actions'][] = $actionConfig;
-
-                    HtmlStack::startJsBuffer();
-                    $actionConfig = ElementHelper::actionConfig(new MoveUp($owner, $attribute));
-                    $actionConfig['bodyHtml'] = HtmlStack::clearJsBuffer();
-                    $settings['indexSettings']['actions'][] = $actionConfig;
-
-                    HtmlStack::startJsBuffer();
-                    $actionConfig = ElementHelper::actionConfig(new MoveDown($owner, $attribute));
-                    $actionConfig['bodyHtml'] = HtmlStack::clearJsBuffer();
-                    $settings['indexSettings']['actions'][] = $actionConfig;
-                }
+        $indexSettings = [
+            'namespace' => InputNamespace::get(),
+            'allowedViewModes' => $config['allowedViewModes']
+                ? array_map(fn ($mode) => Str::toString($mode), $config['allowedViewModes'])
+                : null,
+            'showHeaderColumn' => $config['showHeaderColumn'],
+            'criteria' => array_merge($criteria, $this->criteria),
+            'batchSize' => $config['pageSize'],
+            'actions' => [],
+            'canHaveDrafts' => $config['canHaveDrafts'] ?? $this->elementType::hasDrafts(),
+            'storageKey' => $config['storageKey'],
+            'static' => $config['static'],
+        ];
 
-                return app(ElementIndexHtml::class)->html($this->elementType, [
-                    'class' => [$config['prevalidate'] ? 'prevalidate' : ''],
-                    'context' => 'embedded-index',
-                    'defaultSort' => $config['defaultSort'],
-                    'defaultTableColumns' => $config['defaultTableColumns'],
-                    'defaultViewMode' => $config['defaultViewMode'],
-                    'fieldLayouts' => $config['fieldLayouts'],
-                    'id' => $id,
-                    'prevalidate' => $config['prevalidate'] ?? false,
-                    'registerJs' => false,
-                    'showSiteMenu' => false,
-                    'sources' => false,
-                ]);
-            },
-        );
+        if (! $config['static'] && ($config['sortable'] ?? false)) {
+            foreach ([
+                new ChangeSortOrder($owner, $attribute),
+                new MoveUp($owner, $attribute),
+                new MoveDown($owner, $attribute),
+            ] as $action) {
+                HtmlStack::startJsBuffer();
+                $actionConfig = ElementHelper::actionConfig($action);
+                $actionConfig['bodyHtml'] = HtmlStack::clearJsBuffer();
+                $indexSettings['actions'][] = $actionConfig;
+            }
+        }
+
+        return $indexSettings;
     }
 
     private function createView(?ElementInterface $owner, array $config, string $mode, callable $renderHtml): string
@@ -466,6 +621,30 @@ private function createView(?ElementInterface $owner, array $config, string $mod
             return Html::tag('div', $message, ['class' => 'pane no-border zilch small']);
         }
 
+        $config = $this->normalizeViewConfig($config);
+        $attribute = $this->viewAttribute();
+        $this->authorizeNestedElementManagement($owner, $attribute);
+
+        return InputNamespace::namespaceInputs(function () use ($mode, $attribute, $owner, $config, $renderHtml) {
+            $id = sprintf('element-index-%s', mt_rand());
+
+            $settings = $this->viewSettings($owner, $config, $mode, $attribute);
+
+            $html = $renderHtml($id, $config, $attribute, $settings);
+
+            return Html::tag('craft-nested-element-manager', $html, [
+                'element-type' => $this->elementType,
+                'settings' => Json::encode($settings),
+            ]);
+        }, Html::id($this->field->handle ?? $attribute));
+    }
+
+    /**
+     * Applies the shared view config defaults (create/paste/limit options)
+     * used by both the HTML and data paths.
+     */
+    private function normalizeViewConfig(array $config): array
+    {
         $config += [
             'sortable' => false,
             'canCreate' => false,
@@ -482,64 +661,79 @@ private function createView(?ElementInterface $owner, array $config, string $mod
             ]);
         }
 
+        return $config;
+    }
+
+    /**
+     * The owner attribute (or `field:<handle>`) the nested elements belong to.
+     */
+    private function viewAttribute(): string
+    {
+        return $this->attribute ?? sprintf('field:%s', $this->field->handle);
+    }
+
+    /**
+     * Grants the session authorization the nested-element endpoints require
+     * for this owner/attribute.
+     */
+    private function authorizeNestedElementManagement(ElementInterface $owner, string $attribute): void
+    {
         $authorizedOwnerId = $owner->id;
         if ($owner->isProvisionalDraft && $owner->draftCreatorId === currentUser()?->getCraftUserId()) {
             /** @var ElementInterface $owner */
             $authorizedOwnerId = $owner->getCanonicalId();
         }
 
-        $attribute = $this->attribute ?? sprintf('field:%s', $this->field->handle);
         SessionAuth::authorize(sprintf('manageNestedElements::%s::%s', $authorizedOwnerId, $attribute));
+    }
 
-        return InputNamespace::namespaceInputs(function () use ($mode, $attribute, $owner, $config, $renderHtml) {
-            $id = sprintf('element-index-%s', mt_rand());
-
-            $settings = [
-                'mode' => $mode,
-                'ownerElementType' => $owner::class,
-                'ownerId' => $owner->id,
-                'ownerSiteId' => $owner->siteId,
-                'attribute' => $attribute,
-                'sortable' => $config['sortable'],
-                'canCreate' => $config['canCreate'],
-                'canPaste' => $config['canPaste'],
-                'minElements' => $config['minElements'],
-                'maxElements' => $config['maxElements'],
-                'createButtonLabel' => $config['createButtonLabel'],
-                'ownerIdParam' => $this->ownerIdParam,
-                'fieldId' => $this->field?->id,
-                'fieldHandle' => $this->field?->handle,
-                'baseInputName' => InputNamespace::get(),
-                'prevalidate' => $config['prevalidate'] ?? false,
-            ];
+    /**
+     * Builds the manager settings payload shared by the HTML views (encoded
+     * into `<craft-nested-element-manager settings>`) and the data path
+     * ({@see getIndexData()}).
+     */
+    private function viewSettings(ElementInterface $owner, array $config, string $mode, string $attribute): array
+    {
+        $settings = [
+            'mode' => $mode,
+            'ownerElementType' => $owner::class,
+            'ownerId' => $owner->id,
+            'ownerSiteId' => $owner->siteId,
+            'attribute' => $attribute,
+            'sortable' => $config['sortable'],
+            'canCreate' => $config['canCreate'],
+            'canPaste' => $config['canPaste'],
+            'minElements' => $config['minElements'],
+            'maxElements' => $config['maxElements'],
+            'createButtonLabel' => $config['createButtonLabel'],
+            'ownerIdParam' => $this->ownerIdParam,
+            'fieldId' => $this->field?->id,
+            'fieldHandle' => $this->field?->handle,
+            'baseInputName' => InputNamespace::get(),
+            'prevalidate' => $config['prevalidate'] ?? false,
+        ];
 
-            if (! empty($config['createAttributes'])) {
-                $settings['createAttributes'] = $config['createAttributes'];
-                if (Arr::isIndexed($settings['createAttributes'])) {
-                    if (count($settings['createAttributes']) === 1) {
-                        $settings['createAttributes'] = Arr::first($settings['createAttributes'])['attributes'];
-                    } else {
-                        $settings['createAttributes'] = array_map(function (array $attributes) {
-                            if (isset($attributes['icon'])) {
-                                $attributes['icon'] = Icons::svg($attributes['icon']);
-                            }
-                            if (isset($attributes['color']) && $attributes['color'] instanceof Color) {
-                                $attributes['color'] = $attributes['color']->value;
-                            }
+        if (! empty($config['createAttributes'])) {
+            $settings['createAttributes'] = $config['createAttributes'];
+            if (Arr::isIndexed($settings['createAttributes'])) {
+                if (count($settings['createAttributes']) === 1) {
+                    $settings['createAttributes'] = Arr::first($settings['createAttributes'])['attributes'];
+                } else {
+                    $settings['createAttributes'] = array_map(function (array $attributes) {
+                        if (isset($attributes['icon'])) {
+                            $attributes['icon'] = Icons::svg($attributes['icon']);
+                        }
+                        if (isset($attributes['color']) && $attributes['color'] instanceof Color) {
+                            $attributes['color'] = $attributes['color']->value;
+                        }
 
-                            return $attributes;
-                        }, $settings['createAttributes']);
-                    }
+                        return $attributes;
+                    }, $settings['createAttributes']);
                 }
             }
+        }
 
-            $html = $renderHtml($id, $config, $attribute, $settings);
-
-            return Html::tag('craft-nested-element-manager', $html, [
-                'element-type' => $this->elementType,
-                'settings' => Json::encode($settings),
-            ]);
-        }, Html::id($this->field->handle ?? $attribute));
+        return $settings;
     }
 
     public function maintainNestedElements(ElementInterface $owner, bool $isNew): void
diff --git a/src/Http/ViewModels/UserAddressesViewModel.php b/src/Http/ViewModels/UserAddressesViewModel.php
index 710ea7bc97a..78be4e3b35d 100644
--- a/src/Http/ViewModels/UserAddressesViewModel.php
+++ b/src/Http/ViewModels/UserAddressesViewModel.php
@@ -10,6 +10,75 @@
 use CraftCms\Cms\View\HtmlFragment;
 use Illuminate\Support\Facades\Gate;
 
+/**
+ * @phpstan-type NestedElementCardData array{
+ *     id: int,
+ *     siteId: int|null,
+ *     cardAttributes: array<string, mixed>,
+ *     cardLabelHtml: string,
+ *     cardActionsHtml: string,
+ *     cardContentHtml: string,
+ *     cardThumbHtml: string,
+ *     thumbAlignment: 'start'|'end',
+ * }
+ * @phpstan-type NestedElementCardsData array{
+ *     mode: 'cards',
+ *     elementType: string,
+ *     ownerElementType: string,
+ *     ownerId: int,
+ *     ownerSiteId: int|null,
+ *     attribute: string,
+ *     sortable: bool,
+ *     canCreate: bool,
+ *     canPaste: bool|string,
+ *     minElements: int|null,
+ *     maxElements: int|null,
+ *     createButtonLabel: string,
+ *     ownerIdParam: string,
+ *     fieldId: int|null,
+ *     fieldHandle: string|null,
+ *     baseInputName: string|null,
+ *     prevalidate: bool,
+ *     createAttributes?: mixed,
+ *     deleteLabel: string,
+ *     deleteConfirmationMessage: string,
+ *     bulkDeleteConfirmationMessage: string,
+ *     showInGrid: bool,
+ *     selectable: bool,
+ *     elements: array<int, NestedElementCardData>,
+ * }
+ * @phpstan-type NestedElementIndexData array{
+ *     mode: 'index',
+ *     elementType: string,
+ *     ownerElementType: string,
+ *     ownerId: int,
+ *     ownerSiteId: int|null,
+ *     attribute: string,
+ *     sortable: bool,
+ *     canCreate: bool,
+ *     canPaste: bool|string,
+ *     minElements: int|null,
+ *     maxElements: int|null,
+ *     createButtonLabel: string,
+ *     ownerIdParam: string,
+ *     fieldId: int|null,
+ *     fieldHandle: string|null,
+ *     baseInputName: string|null,
+ *     prevalidate: bool,
+ *     createAttributes?: mixed,
+ *     indexSettings: array{
+ *         namespace: string|null,
+ *         allowedViewModes: array<int, string>|null,
+ *         showHeaderColumn: bool,
+ *         criteria: array<string, mixed>,
+ *         batchSize: int,
+ *         actions: array<int, array<string, mixed>>,
+ *         canHaveDrafts: bool,
+ *         storageKey: string|null,
+ *         static: bool,
+ *     },
+ * }
+ */
 class UserAddressesViewModel extends ViewModel
 {
     /**
@@ -33,6 +102,31 @@ public function showIndex(): bool
         return $this->totalAddresses() > self::CARD_LIMIT;
     }
 
+    /**
+     * The nested element manager payload for a Vue-rendered addresses UI:
+     * cards data (with per-element card parts) up to the card limit, or
+     * embedded element index data beyond it.
+     *
+     * @return NestedElementCardsData|NestedElementIndexData
+     */
+    public function data(): array
+    {
+        $config = [
+            'showInGrid' => true,
+            'canCreate' => Gate::check('editUsers'),
+        ];
+
+        $data = $this->showIndex()
+            ? $this->user->getAddressManager()->getIndexData($this->user, $config)
+            : $this->user->getAddressManager()->getCardsData($this->user, $config);
+
+        // The view model's user is always saved, so the managers never
+        // return their unsaved-owner null.
+        assert($data !== null);
+
+        return $data;
+    }
+
     public function contentFragment(): HtmlFragment
     {
         $config = [
diff --git a/tests-playwright/tests/account/addresses.test.js b/tests-playwright/tests/account/addresses.test.js
new file mode 100644
index 00000000000..968738f1dd2
--- /dev/null
+++ b/tests-playwright/tests/account/addresses.test.js
@@ -0,0 +1,198 @@
+/* jshint esversion: 9, strict: false */
+/* globals module, require */
+const {test, expect} = require('../../index');
+
+const slideoutLocator = '.slideout-container:not(.hidden)';
+
+test.beforeAll(async ({craftSetup}) => {
+  await craftSetup.cleanAll();
+});
+
+test.beforeEach(async ({page}) => {
+  await page.goto('./myaccount/addresses');
+});
+
+/**
+ * A card in the address grid, singled out by its label.
+ */
+function cardByLabel(page, label) {
+  return page.locator('craft-card').filter({hasText: label});
+}
+
+/**
+ * Opens a card's action menu and returns the menu item with the given label.
+ */
+async function openCardActionItem(page, card, itemLabel) {
+  await card.getByRole('button', {name: 'Actions'}).click();
+  return card.locator('craft-action-item').filter({hasText: itemLabel});
+}
+
+/**
+ * Creates an address through the "New address" flow and waits for its card
+ * to appear.
+ */
+async function createAddress(page, label) {
+  const slideout = page.locator(slideoutLocator);
+
+  await page.getByRole('button', {name: 'New address'}).click();
+  await slideout.waitFor();
+
+  await slideout.locator('input[name$="[title]"]').fill(label);
+  await slideout.locator('input[name$="[addressLine1]"]').fill('123 Main Street');
+  await slideout.locator('input[name$="[locality]"]').fill('Portland');
+  await slideout.locator('input[name$="[postalCode]"]').fill('97201');
+
+  await page.getByRole('button', {name: 'Create address'}).click();
+  await slideout.waitFor({state: 'hidden'});
+
+  await expect(cardByLabel(page, label)).toBeVisible();
+}
+
+test.describe('Creating addresses', () => {
+  test('The New address button opens an editor slideout', async ({page}) => {
+    await page.getByRole('button', {name: 'New address'}).click();
+
+    const slideout = page.locator(slideoutLocator);
+    await expect(slideout.locator('input[name$="[title]"]')).toBeVisible();
+    await expect(
+      page.getByRole('button', {name: 'Create address'})
+    ).toBeVisible();
+
+    await page.getByRole('button', {name: 'Cancel'}).click();
+    await slideout.waitFor({state: 'hidden'});
+  });
+
+  test('A created address appears as a card', async ({page}) => {
+    const label = 'Created address';
+
+    await createAddress(page, label);
+
+    const card = cardByLabel(page, label);
+    await expect(card).toContainText('123 Main Street');
+    await expect(card).toContainText('Portland');
+  });
+});
+
+test.describe('Editing addresses', () => {
+  test('Edits made in the slideout show on the card after saving', async ({
+    page,
+  }) => {
+    const label = 'Edit target';
+    const editedLabel = 'Edit target (edited)';
+
+    await createAddress(page, label);
+
+    const slideout = page.locator(slideoutLocator);
+    await cardByLabel(page, label)
+      .getByRole('button', {name: 'Edit address'})
+      .click();
+    await slideout.waitFor();
+
+    await expect(slideout.locator('input[name$="[title]"]')).toHaveValue(
+      label
+    );
+    await slideout.locator('input[name$="[title]"]').fill(editedLabel);
+    await slideout.locator('input[name$="[addressLine1]"]').fill('1 Edited Road');
+    await page.getByRole('button', {name: 'Save', exact: true}).click();
+    await slideout.waitFor({state: 'hidden'});
+
+    const card = cardByLabel(page, editedLabel);
+    await expect(card).toBeVisible();
+    await expect(card).toContainText('1 Edited Road');
+  });
+
+  test('Cancelling an edit leaves the card unchanged', async ({page}) => {
+    const label = 'Cancelled edit';
+
+    await createAddress(page, label);
+
+    const slideout = page.locator(slideoutLocator);
+    await cardByLabel(page, label)
+      .getByRole('button', {name: 'Edit address'})
+      .click();
+    await slideout.waitFor();
+
+    await slideout.locator('input[name$="[title]"]').fill('Discarded label');
+    await page.getByRole('button', {name: 'Cancel'}).click();
+    await slideout.waitFor({state: 'hidden'});
+
+    await expect(cardByLabel(page, label)).toBeVisible();
+    await expect(cardByLabel(page, 'Discarded label')).toHaveCount(0);
+  });
+});
+
+test.describe('Deleting addresses', () => {
+  test('Deleting an address removes its card', async ({page}) => {
+    const label = 'Delete target';
+
+    await createAddress(page, label);
+
+    const card = cardByLabel(page, label);
+    const deleteItem = await openCardActionItem(page, card, 'Delete address');
+
+    // Deleting asks for confirmation first.
+    page.once('dialog', (dialog) => dialog.accept());
+    await deleteItem.click();
+
+    await expect(card).toHaveCount(0);
+  });
+
+  test('Dismissing the confirmation keeps the address', async ({page}) => {
+    const label = 'Kept address';
+
+    await createAddress(page, label);
+
+    const card = cardByLabel(page, label);
+    const deleteItem = await openCardActionItem(page, card, 'Delete address');
+
+    page.once('dialog', (dialog) => dialog.dismiss());
+    await deleteItem.click();
+
+    await expect(card).toBeVisible();
+  });
+});
+
+test.describe('Duplicating addresses', () => {
+  test('Duplicating an address adds a second card with the same content', async ({
+    page,
+  }) => {
+    const label = 'Duplicate target';
+
+    await createAddress(page, label);
+
+    const card = cardByLabel(page, label).first();
+    const duplicateItem = await openCardActionItem(page, card, 'Duplicate');
+    await duplicateItem.click();
+
+    await expect(cardByLabel(page, label)).toHaveCount(2);
+  });
+});
+
+test.describe('Copying addresses', () => {
+  test('Copying an address shows a copied notification', async ({page}) => {
+    const label = 'Copy target';
+
+    await createAddress(page, label);
+
+    const card = cardByLabel(page, label);
+    const copyItem = await openCardActionItem(page, card, 'Copy address');
+    await copyItem.click();
+
+    await expect(page.getByText(/copied/i)).toBeVisible();
+  });
+
+  test('A copied address can be pasted as a new card', async ({page}) => {
+    const label = 'Paste source';
+
+    await createAddress(page, label);
+
+    const card = cardByLabel(page, label);
+    const copyItem = await openCardActionItem(page, card, 'Copy address');
+    await copyItem.click();
+
+    // The copied element is offered as a paste action.
+    await page.getByRole('button', {name: /Paste/}).click();
+
+    await expect(cardByLabel(page, label)).toHaveCount(2);
+  });
+});
diff --git a/tests/Feature/Element/NestedElementManagerTest.php b/tests/Feature/Element/NestedElementManagerTest.php
index f967abcd1d3..ad24b154165 100644
--- a/tests/Feature/Element/NestedElementManagerTest.php
+++ b/tests/Feature/Element/NestedElementManagerTest.php
@@ -300,6 +300,105 @@ function createMatrixQuery(Matrix $field, ?ElementInterface $owner): EntryQuery
         ->not->toBeNull();
 });
 
+it('provides index data matching the rendered index settings', function () {
+    $user = UserModel::factory()->createElement();
+    $manager = $user->getAddressManager();
+
+    $data = $manager->getIndexData($user, ['sortable' => true]);
+
+    expect($data)->not->toBeNull()
+        ->and($data['mode'])->toBe('index')
+        ->and($data['ownerId'])->toBe($user->id)
+        ->and($data['elementType'])->toBe(AddressElement::class)
+        ->and($data['attribute'])->toBe('addresses')
+        ->and($data['indexSettings']['criteria']['ownerId'])->toBe($user->id)
+        ->and($data['indexSettings']['actions'])->toHaveCount(3);
+
+    // The data payload matches what the HTML path encodes into the
+    // <craft-nested-element-manager settings> attribute. Namespace-derived
+    // keys differ (the HTML path computes inside its input namespace) and
+    // the action configs carry per-render markup, so both are normalized
+    // out of the comparison.
+    $html = $manager->getIndexHtml($user, ['sortable' => true]);
+    expect(preg_match('/settings="([^"]+)"/', (string) $html, $matches))->toBe(1);
+    $encoded = json_decode(html_entity_decode($matches[1], ENT_QUOTES), true);
+    expect($encoded['indexSettings']['actions'])->toHaveCount(3);
+
+    $normalize = function (array $settings): array {
+        // `elementType` is a data-path addition (the HTML path passes it as
+        // the `element-type` attribute instead).
+        unset(
+            $settings['baseInputName'],
+            $settings['elementType'],
+            $settings['indexSettings']['namespace'],
+            $settings['indexSettings']['actions'],
+        );
+
+        return $settings;
+    };
+
+    expect($normalize($data))->toBe($normalize($encoded));
+});
+
+it('provides cards data matching the rendered cards settings', function () {
+    $user = UserModel::factory()->createElement();
+    $address = AddressModel::factory()->createElement([
+        'primaryOwnerId' => $user->id,
+    ]);
+
+    DB::table(Table::ELEMENTS_OWNERS)->insert([
+        'elementId' => $address->id,
+        'ownerId' => $user->id,
+        'sortOrder' => 1,
+    ]);
+
+    $manager = $user->getAddressManager();
+    $data = $manager->getCardsData($user, ['showInGrid' => true]);
+
+    expect($data)->not->toBeNull()
+        ->and($data['mode'])->toBe('cards')
+        ->and($data['ownerId'])->toBe($user->id)
+        ->and($data['elementType'])->toBe(AddressElement::class)
+        ->and($data['showInGrid'])->toBeTrue()
+        ->and($data['elements'])->toHaveCount(1);
+
+    $card = $data['elements'][0];
+    expect($card['id'])->toBe($address->id)
+        ->and($card['cardAttributes'])->toBeArray()
+        ->and($card['cardLabelHtml'])->toBeString()
+        ->and($card['cardActionsHtml'])->toBeString()
+        ->and($card['cardContentHtml'])->not->toBe('')
+        // The thumb is provided separately for a card component's thumbnail
+        // slot; the content part omits it.
+        ->and($card['cardContentHtml'])->not->toContain('thumb')
+        ->and($card['cardThumbHtml'])->toBeString()
+        ->and($card['thumbAlignment'])->toBeIn(['start', 'end']);
+
+    // The settings match what the HTML path encodes into the
+    // <craft-nested-element-manager settings> attribute; `elements` is the
+    // data path's addition, and `baseInputName` is namespace-derived.
+    $html = $manager->getCardsHtml($user, ['showInGrid' => true]);
+    expect(preg_match('/settings="([^"]+)"/', (string) $html, $matches))->toBe(1);
+    $encoded = json_decode(html_entity_decode($matches[1], ENT_QUOTES), true);
+
+    $normalize = function (array $settings): array {
+        unset($settings['baseInputName'], $settings['elementType'], $settings['elements']);
+
+        return $settings;
+    };
+
+    expect($normalize($data))->toBe($normalize($encoded));
+});
+
+it('returns no index or cards data for unsaved owners', function () {
+    $user = UserModel::factory()->createElement();
+
+    expect($user->getAddressManager()->getIndexData(new User))->toBeNull()
+        ->and($user->getAddressManager()->getIndexData(null))->toBeNull()
+        ->and($user->getAddressManager()->getCardsData(new User))->toBeNull()
+        ->and($user->getAddressManager()->getCardsData(null))->toBeNull();
+});
+
 it('deletes and restores attribute-backed user addresses with owner state', function () {
     $user = UserModel::factory()->createElement();
     $address = AddressModel::factory()->createElement([

From 4657bc65a16de95565b80ef94a6829e516e787a3 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Mon, 27 Jul 2026 15:01:17 -0500
Subject: [PATCH 13/15] Add playwright tests

---
 playwright.config.js                          |  2 +-
 tests-playwright/package.json                 |  3 ++
 .../tests/account/addresses.test.js           | 35 +++++++++++++------
 3 files changed, 28 insertions(+), 12 deletions(-)
 create mode 100644 tests-playwright/package.json

diff --git a/playwright.config.js b/playwright.config.js
index 9049a214127..b0031b1f33a 100644
--- a/playwright.config.js
+++ b/playwright.config.js
@@ -1,3 +1,3 @@
-const craftPlaywright = require('@craftcms/playwright');
+import craftPlaywright from '@craftcms/playwright';
 
 export default craftPlaywright.getConfig();
diff --git a/tests-playwright/package.json b/tests-playwright/package.json
new file mode 100644
index 00000000000..5bbefffbabe
--- /dev/null
+++ b/tests-playwright/package.json
@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}
diff --git a/tests-playwright/tests/account/addresses.test.js b/tests-playwright/tests/account/addresses.test.js
index 968738f1dd2..e0243026212 100644
--- a/tests-playwright/tests/account/addresses.test.js
+++ b/tests-playwright/tests/account/addresses.test.js
@@ -4,6 +4,15 @@ const {test, expect} = require('../../index');
 
 const slideoutLocator = '.slideout-container:not(.hidden)';
 
+/**
+ * Address labels are made unique per run so leftover cards from an earlier
+ * run (e.g. when the database isn't restored between runs) can't collide
+ * with this run's locators.
+ */
+function uniqueLabel(name) {
+  return `${name} ${Date.now()}`;
+}
+
 test.beforeAll(async ({craftSetup}) => {
   await craftSetup.cleanAll();
 });
@@ -63,7 +72,7 @@ test.describe('Creating addresses', () => {
   });
 
   test('A created address appears as a card', async ({page}) => {
-    const label = 'Created address';
+    const label = uniqueLabel('Created address');
 
     await createAddress(page, label);
 
@@ -77,8 +86,8 @@ test.describe('Editing addresses', () => {
   test('Edits made in the slideout show on the card after saving', async ({
     page,
   }) => {
-    const label = 'Edit target';
-    const editedLabel = 'Edit target (edited)';
+    const label = uniqueLabel('Edit target');
+    const editedLabel = label + ' (edited)';
 
     await createAddress(page, label);
 
@@ -102,7 +111,8 @@ test.describe('Editing addresses', () => {
   });
 
   test('Cancelling an edit leaves the card unchanged', async ({page}) => {
-    const label = 'Cancelled edit';
+    const label = uniqueLabel('Cancelled edit');
+    const discardedLabel = label + ' (discarded)';
 
     await createAddress(page, label);
 
@@ -112,18 +122,21 @@ test.describe('Editing addresses', () => {
       .click();
     await slideout.waitFor();
 
-    await slideout.locator('input[name$="[title]"]').fill('Discarded label');
+    await slideout.locator('input[name$="[title]"]').fill(discardedLabel);
+
+    // Cancelling a dirty editor asks whether to discard the changes.
+    page.once('dialog', (dialog) => dialog.accept());
     await page.getByRole('button', {name: 'Cancel'}).click();
     await slideout.waitFor({state: 'hidden'});
 
     await expect(cardByLabel(page, label)).toBeVisible();
-    await expect(cardByLabel(page, 'Discarded label')).toHaveCount(0);
+    await expect(cardByLabel(page, discardedLabel)).toHaveCount(0);
   });
 });
 
 test.describe('Deleting addresses', () => {
   test('Deleting an address removes its card', async ({page}) => {
-    const label = 'Delete target';
+    const label = uniqueLabel('Delete target');
 
     await createAddress(page, label);
 
@@ -138,7 +151,7 @@ test.describe('Deleting addresses', () => {
   });
 
   test('Dismissing the confirmation keeps the address', async ({page}) => {
-    const label = 'Kept address';
+    const label = uniqueLabel('Kept address');
 
     await createAddress(page, label);
 
@@ -156,7 +169,7 @@ test.describe('Duplicating addresses', () => {
   test('Duplicating an address adds a second card with the same content', async ({
     page,
   }) => {
-    const label = 'Duplicate target';
+    const label = uniqueLabel('Duplicate target');
 
     await createAddress(page, label);
 
@@ -170,7 +183,7 @@ test.describe('Duplicating addresses', () => {
 
 test.describe('Copying addresses', () => {
   test('Copying an address shows a copied notification', async ({page}) => {
-    const label = 'Copy target';
+    const label = uniqueLabel('Copy target');
 
     await createAddress(page, label);
 
@@ -182,7 +195,7 @@ test.describe('Copying addresses', () => {
   });
 
   test('A copied address can be pasted as a new card', async ({page}) => {
-    const label = 'Paste source';
+    const label = uniqueLabel('Paste source');
 
     await createAddress(page, label);
 

From b966496f85534087d3d1f3f93b1cb439f366b8d0 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Tue, 28 Jul 2026 09:37:51 -0500
Subject: [PATCH 14/15] Wire duplicate/delete actions for data-path nested
 cards

Cards-data menu items now carry self-contained duplicate/delete HTTP
actions, the addresses page restores its empty state and refreshes via
partial reloads on action success, and AGENTS.md notes the VueUse
utilities.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 AGENTS.md                                     |  4 ++
 resources/js/pages/users/Addresses.vue        | 33 ++++++++++-----
 src/Cp/Html/ElementHtml.php                   | 40 +++++++++++++++++--
 src/Element/NestedElementManager.php          | 12 +++++-
 .../Element/NestedElementManagerTest.php      | 38 ++++++++++++++++++
 .../User/AddressesControllerTest.php          |  2 +
 6 files changed, 115 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b8f00838ce0..bafa24d1f3c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,6 +70,10 @@ The CP has two parallel rendering stacks that are actively being consolidated:
 components in `resources/js/common/`. `HandleInertiaRequests` middleware provides shared CP config, navigation, and
 global props to all Inertia pages. The root Blade template is `resources/views/app.blade.php`.
 
+VueUse (`@vueuse/core`) is installed — before hand-rolling composable behavior in Vue code (event listeners with
+mount/unmount cleanup, media queries, storage, observers, etc.), check whether a VueUse utility already covers it
+(e.g. `useEventListener` accepts ref targets and cleans up automatically, `useMediaQuery`).
+
 **Legacy jQuery (old):** `resources/js/legacy.ts` loads the old surface. The individual jQuery modules live in
 `packages/craftcms-legacy/` and are bundled with webpack (separate from Vite). Pages still on this stack return `view()`
 from their controllers.
diff --git a/resources/js/pages/users/Addresses.vue b/resources/js/pages/users/Addresses.vue
index 950a4dadb46..f9a4ce1433f 100644
--- a/resources/js/pages/users/Addresses.vue
+++ b/resources/js/pages/users/Addresses.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
-  import {computed, onBeforeUnmount, onMounted, ref} from 'vue';
+  import {computed, ref} from 'vue';
   import {router, usePage} from '@inertiajs/vue3';
+  import {useEventListener} from '@vueuse/core';
   import {attrs, t} from '@craftcms/ui';
   import LayoutSlot from '@/common/components/LayoutSlot.vue';
   import Pane from '@/common/components/Pane.vue';
@@ -101,25 +102,37 @@
   };
 
   // Refresh the cards when an editor slideout saves an element.
-  const onElementSaved = () => {
+  useEventListener(window, 'craft:element-saved', () => {
     router.reload({only: ['data']});
-  };
-
-  onMounted(() => {
-    window.addEventListener('craft:element-saved', onElementSaved);
   });
 
-  onBeforeUnmount(() => {
-    window.removeEventListener('craft:element-saved', onElementSaved);
+  // The listener lives on the cards' stable wrapper (not the grid itself,
+  // which is `v-if`-ed away when the last card is deleted).
+  const cardsContainer = ref<HTMLElement | null>(null);
+
+  // The cards' server-provided action items (e.g. Delete) run their HTTP
+  // request themselves via the action system and announce progress through
+  // bubbling `action:change-state` events — refresh the cards once one
+  // succeeds.
+  useEventListener(cardsContainer, 'action:change-state', (event: Event) => {
+    const detail = (event as CustomEvent).detail;
+
+    if (detail?.state === 'success' && detail?.actionType === 'http') {
+      router.reload({only: ['data']});
+    }
   });
 </script>
 
 <template>
   <Pane appearance="raised">
-    <div class="grid gap-3">
+    <div ref="cardsContainer" class="grid gap-3">
       <h2 v-if="!props.showIndex" class="text-lg m-0!">{{ t('Addresses') }}</h2>
 
-      <div class="card-grid">
+      <craft-empty v-if="cardsData && !cardsData.elements.length">
+        {{ t('Nothing yet.') }}
+      </craft-empty>
+
+      <div v-if="cardsData?.elements.length" class="card-grid">
         <template v-for="element in cardsData?.elements" :key="element.id">
           <craft-card
             v-bind="attrs(element.cardAttributes, {exclude: ['class']})"
diff --git a/src/Cp/Html/ElementHtml.php b/src/Cp/Html/ElementHtml.php
index 8507300fc61..ac4eee4689c 100644
--- a/src/Cp/Html/ElementHtml.php
+++ b/src/Cp/Html/ElementHtml.php
@@ -343,7 +343,12 @@ public function elementChipHtml(ElementInterface $element, array $config = []):
      *   paths that know the card belongs to a nested-element context
      *   ({@see NestedElementManager::getCardsHtml()},
      *   `app/render-elements`), never by client-supplied configs — with each
-     *   item gated on the current user's permissions
+     *   item gated on the current user's permissions. May also be the owner
+     *   context as an array (`ownerElementType`/`ownerId`/`ownerSiteId`/
+     *   `attribute` — {@see NestedElementManager::getCardsData()}), in which
+     *   case the Duplicate and Delete items carry self-contained
+     *   `elements/duplicate`/`nested-elements/delete` actions instead of
+     *   relying on a hosting manager
      * - `showEditButton` – Whether the card should include an edit button
      * - `sortable` – Whether the card should include a drag handle
      */
@@ -666,17 +671,33 @@ private function nestedCardActionItems(ElementInterface $element, array $config)
         }
 
         if (Gate::check('duplicate', $element)) {
-            $items[] = [
+            $item = [
                 'icon' => 'clone',
                 'label' => t('Duplicate'),
                 'attributes' => [
                     'data' => ['duplicate-action' => true],
                 ],
             ];
+
+            // With a known owner context (`showNestedActions` as an array —
+            // the data path, where no `Craft.NestedElementManager` wires the
+            // markers), the item carries a self-contained duplicate action,
+            // mirroring the legacy manager's `duplicateElement()` request.
+            if (is_array($config['showNestedActions'])) {
+                $item['action'] = 'elements/duplicate';
+                $item['params'] = [
+                    'elementType' => $element::class,
+                    'elementId' => $element->id,
+                    'ownerId' => $config['showNestedActions']['ownerId'],
+                    'siteId' => $config['showNestedActions']['ownerSiteId'],
+                ];
+            }
+
+            $items[] = $item;
         }
 
         if (Gate::check('delete', $element)) {
-            $items[] = [
+            $item = [
                 'icon' => 'trash',
                 'label' => mb_ucfirst(t('Delete {type}', [
                     'type' => $element::lowerDisplayName(),
@@ -686,6 +707,19 @@ private function nestedCardActionItems(ElementInterface $element, array $config)
                     'data' => ['delete-action' => true],
                 ],
             ];
+
+            // With a known owner context (`showNestedActions` as an array —
+            // the data path, where no `Craft.NestedElementManager` wires the
+            // markers), the item carries a self-contained delete action.
+            if (is_array($config['showNestedActions'])) {
+                $item['action'] = 'nested-elements/delete';
+                $item['params'] = $config['showNestedActions'] + ['elementId' => $element->id];
+                $item['confirm'] = t('Are you sure you want to delete the selected {type}?', [
+                    'type' => $element::lowerDisplayName(),
+                ]);
+            }
+
+            $items[] = $item;
         }
 
         return $items;
diff --git a/src/Element/NestedElementManager.php b/src/Element/NestedElementManager.php
index eb5074e5337..02a35e65def 100644
--- a/src/Element/NestedElementManager.php
+++ b/src/Element/NestedElementManager.php
@@ -314,15 +314,25 @@ public function getCardsData(?ElementInterface $owner, array $config = []): ?arr
         $settings['elementType'] = $this->elementType;
 
         $elementHtml = app(ElementHtml::class);
-        $settings['elements'] = array_map(function (ElementInterface $element) use ($elementHtml, $config): array {
+        $settings['elements'] = array_map(function (ElementInterface $element) use ($elementHtml, $config, $owner, $attribute): array {
             // A per-element `id` is shared across the card parts so they line
             // up when recomposed client-side, while staying unique per card.
             // The thumb is provided separately (for a card component's
             // `thumbnail` slot), so the content part omits it.
+            // Unlike the HTML view (where a hosting `Craft.NestedElementManager`
+            // wires the nested action markers itself), the data path has no
+            // manager — passing the owner context makes the Delete item a
+            // self-contained HTTP action.
             $cardConfig = $this->cardConfig($config) + [
                 'id' => sprintf('card-%s', mt_rand()),
                 'withThumb' => false,
             ];
+            $cardConfig['showNestedActions'] = [
+                'ownerElementType' => $owner::class,
+                'ownerId' => $owner->id,
+                'ownerSiteId' => $owner->siteId,
+                'attribute' => $attribute,
+            ];
 
             return [
                 'id' => $element->id,
diff --git a/tests/Feature/Element/NestedElementManagerTest.php b/tests/Feature/Element/NestedElementManagerTest.php
index 72dd17a216d..76b94ecc159 100644
--- a/tests/Feature/Element/NestedElementManagerTest.php
+++ b/tests/Feature/Element/NestedElementManagerTest.php
@@ -399,6 +399,44 @@ function createMatrixQuery(Matrix $field, ?ElementInterface $owner): EntryQuery
     expect($normalize($data))->toBe($normalize($encoded));
 });
 
+it('gives cards-data menu items self-contained duplicate/delete actions', function () {
+    $user = UserModel::factory()->createElement();
+    $address = AddressModel::factory()->createElement([
+        'primaryOwnerId' => $user->id,
+    ]);
+
+    DB::table(Table::ELEMENTS_OWNERS)->insert([
+        'elementId' => $address->id,
+        'ownerId' => $user->id,
+        'sortOrder' => 1,
+    ]);
+
+    $manager = $user->getAddressManager();
+
+    // The data path has no hosting manager to wire the delete marker, so the
+    // item carries the full HTTP action, targeting the owner context.
+    $data = $manager->getCardsData($user, ['showInGrid' => true]);
+    $actionsHtml = $data['elements'][0]['cardActionsHtml'];
+    expect($actionsHtml)->toContain('data-delete-action')
+        ->and($actionsHtml)->toContain('nested-elements/delete')
+        ->and($actionsHtml)->toContain(sprintf('elementId&quot;:%d', $address->id))
+        ->and($actionsHtml)->toContain(sprintf('ownerId&quot;:%d', $user->id))
+        ->and($actionsHtml)->toContain('attribute&quot;:&quot;addresses&quot;');
+
+    // Same for the duplicate marker.
+    expect($actionsHtml)->toContain('data-duplicate-action')
+        ->and($actionsHtml)->toContain('elements/duplicate');
+
+    // The HTML view keeps the markers behavior-less — the hosting
+    // `Craft.NestedElementManager` wires them (with draft handling the
+    // static actions can't know about).
+    $html = $manager->getCardsHtml($user, ['showInGrid' => true]);
+    expect($html)->toContain('data-delete-action')
+        ->and($html)->not->toContain('nested-elements/delete')
+        ->and($html)->toContain('data-duplicate-action')
+        ->and($html)->not->toContain('elements/duplicate');
+});
+
 it('returns no index or cards data for unsaved owners', function () {
     $user = UserModel::factory()->createElement();
 
diff --git a/tests/Feature/Http/Controllers/User/AddressesControllerTest.php b/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
index 143469a9b97..3d7ff26121d 100644
--- a/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
+++ b/tests/Feature/Http/Controllers/User/AddressesControllerTest.php
@@ -47,6 +47,7 @@
         ->assertOk()
         ->assertInertia(fn (AssertableInertia $page) => $page
             ->component('users/Addresses')
+            ->where('data.elements.0.cardActionsHtml', fn (string $html): bool => str_contains($html, 'data-duplicate-action') && str_contains($html, 'data-delete-action'))
             ->where('contentFragment.html', fn (string $html): bool => str_contains($html, 'data-duplicate-action') && str_contains($html, 'data-delete-action')));
 });
 
@@ -61,6 +62,7 @@
             ->has('crumbs', 2)
             ->has('subnav')
             ->has('details')
+            ->where('data.mode', 'cards')
             ->where('contentFragment.html', fn (string $html): bool => $html !== ''));
 });
 

From a02e8bda9728dbfb12f784ef0c7032dc842c534b Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Tue, 28 Jul 2026 09:49:15 -0500
Subject: [PATCH 15/15] Make sure to render something for 50+ addresses

---
 resources/js/pages/users/Addresses.vue | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/resources/js/pages/users/Addresses.vue b/resources/js/pages/users/Addresses.vue
index f9a4ce1433f..6e1814455b1 100644
--- a/resources/js/pages/users/Addresses.vue
+++ b/resources/js/pages/users/Addresses.vue
@@ -6,6 +6,7 @@
   import LayoutSlot from '@/common/components/LayoutSlot.vue';
   import Pane from '@/common/components/Pane.vue';
   import DynamicHtmlRenderer from '@/common/components/DynamicHtmlRenderer.vue';
+  import HtmlFragmentRenderer from '@/common/components/HtmlFragmentRenderer.vue';
 
   defineOptions({
     inheritAttrs: false,
@@ -27,6 +28,13 @@
     page.props.data.mode === 'cards' ? page.props.data : null
   );
 
+  // Past the card limit the server switches to index mode; the embedded
+  // element index arrives as a server-rendered fragment whose
+  // `<craft-nested-element-manager>` wrapper initializes itself once injected.
+  const indexFragment = computed(() =>
+    page.props.data.mode === 'index' ? page.props.contentFragment : null
+  );
+
   const createBtn = ref<HTMLElement | null>(null);
   const creating = ref(false);
 
@@ -128,6 +136,8 @@
     <div ref="cardsContainer" class="grid gap-3">
       <h2 v-if="!props.showIndex" class="text-lg m-0!">{{ t('Addresses') }}</h2>
 
+      <HtmlFragmentRenderer v-if="indexFragment" :fragment="indexFragment" />
+
       <craft-empty v-if="cardsData && !cardsData.elements.length">
         {{ t('Nothing yet.') }}
       </craft-empty>