article
+
+
+ A slotted label can carry richer content than plain text — icons, handles,
+ badges.
+
+ Custom header
+ anything goes here
+
+
+ When the header slot is filled, the default label/actions layout is
+ replaced entirely.
+
+ Updated 2 hours ago
+ Draft
+
+ thumb-alignment puts it at the start or end of the body.
+
+
+ ${placeholderThumb} Thumbnail leading the body content.
+
+
+ ${placeholderThumb} Thumbnail trailing the body content.
+
+
+ `,
+};
+
+/** The reflected `active` attribute marks selection (e.g. element index rows). */
+export const Active: Story = {
+ render: ({label}) => html`
+
+ An inactive card for comparison.
+
+ An active card — loud header/footer fill and border.
+
+
+ `,
+};
+
+/** Radius, shadow, and padding are themeable via custom properties. */
+export const CustomProperties: Story = {
+ render: ({label}) => html`
+ --c-card-* custom properties.
+ + Header label and actions, a leading thumbnail, body content, and a + metadata footer — all regions at once. +
+ +
+ Posted Oct 14
+ Live
+
+
${hasSlottedHeader
@@ -93,7 +130,7 @@ export default class CraftCard extends LitElement {
${this.label}
-
`
: 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',
})}"
>
-
+
{
+ return html`
+ ;
+
+export default meta;
+type Story = StoryObj;
+
+// 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`
+
+ New entry
+
+ `;
+ },
+};
+
+export const CustomContent: Story = {
+ render: ({icon}) => {
+ return html`
+
+ Clear filters
+
+ `;
+ },
+};
+
+export const CustomGraphic: Story = {
+ render: ({label}) => {
+ return html`
+
+
+
+ `;
+ },
+};
diff --git a/packages/craftcms-ui/src/components/empty/empty.ts b/packages/craftcms-ui/src/components/empty/empty.ts
index 356d9b9d2fb..352ec9eb578 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`
+
+ + No entries match your search. +
+Try a different keyword, or clear the filters.
+
diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index dd43dfd4354..1f0893b47b8 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';
@@ -81,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: 'Fancy'});
+
+ 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 ``. */
+ 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;
+ /**
+ * 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 ``. The label lives in a slotted
+ * ``, 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 `` (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" `` (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/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/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/cp.ts b/resources/js/cp.ts
index e26caa33090..a1b5e22c556 100644
--- a/resources/js/cp.ts
+++ b/resources/js/cp.ts
@@ -19,6 +19,8 @@ import './modules/grouped-entry-type-manager';
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 c91cae93529..8ac9e96b9d7 100644
--- a/resources/js/legacy.ts
+++ b/resources/js/legacy.ts
@@ -18,6 +18,8 @@ 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';
+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): 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 {
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 {
async pasteEntries(before: HTMLElement | null = null): Promise {
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 {
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 {
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/nested-element-manager/README.md b/resources/js/modules/nested-element-manager/README.md
new file mode 100644
index 00000000000..3904b2e4c02
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/README.md
@@ -0,0 +1,72 @@
+# 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
+ `` 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 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,
+ 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';
+
+/**
+ * `` — 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
+ * ``'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 {
+ // 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;
+
+ 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..42002ae31ad
--- /dev/null
+++ b/resources/js/modules/nested-element-manager/nested-element-manager.ts
@@ -0,0 +1,1363 @@
+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;
+}
+
+/**
+ * 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:`) the nested elements belong to. */
+ attribute: string | null;
+ selectable: boolean;
+ sortable: boolean;
+ /** Extra settings for the embedded element index (index mode). */
+ indexSettings: Record;
+ 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 | null;
+ /** Extra params merged into paste requests. */
+ pasteAttributes: Record | 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. 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
+ * 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 {
+ static defaults: Omit = {
+ 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[] = [];
+ /** Teardown callbacks for per-card native listeners (delete items, …). */
+ #disposers: Array<() => void> = [];
+ #afterInitTimeout: ReturnType | null = null;
+
+ constructor(
+ container: HTMLElement | string,
+ elementTypeOrSettings?: string | Partial,
+ legacySettings?: Partial
+ ) {
+ super();
+
+ // Legacy signature: (container, elementType, settings).
+ let settings: Partial;
+ if (typeof elementTypeOrSettings === 'string') {
+ settings = {...legacySettings, elementType: elementTypeOrSettings};
+ } else {
+ settings = elementTypeOrSettings ?? {};
+ }
+
+ const resolved =
+ typeof container === 'string'
+ ? document.querySelector(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);
+ }
+ this.#syncCardActionItems();
+ });
+ }
+
+ // --- 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)}`;
+ $('', {
+ 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 = {};
+ 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 = $(
+ ''
+ ).insertAfter($createBtn);
+ $collapsedContainer.append($createBtn);
+ const $expandedContainer = $(
+ ''
+ ).insertAfter($collapsedContainer);
+
+ // Add a SR-only description for each disclosure button
+ const btngroupDescriptionId = `btngroup-desc-${Math.floor(
+ Math.random() * 100000
+ )}`;
+ const $btngroupDescription = $('', {
+ 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
+ )}`;
+ $('', {
+ 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 | 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 = $('', {
+ class: 'flex flex-inline',
+ }).appendTo(this.container);
+ }
+ $button.appendTo(this.$btnContainer);
+ this.updateCreateBtn();
+ } else {
+ $button.appendTo(this.elementIndex.$toolbar);
+ }
+ }
+
+ updateCreateBtn(): void {
+ this.#syncCardActionItems();
+
+ 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 = $('('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(
+ ':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('craft-empty').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 {
+ if (!this.elementEditor || !this.settings.baseInputName) {
+ return false;
+ }
+ return await this.elementEditor.setFormValue(
+ this.settings.baseInputName,
+ '*'
+ );
+ }
+
+ async getBaseActionData(): Promise> {
+ // 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 {
+ // The DOM order just changed — re-gate the cards' Move items.
+ this.#syncCardActionItems();
+
+ 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 {
+ 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 | null
+ ): Promise {
+ 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 {
+ 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 {
+ for (const element of $(elements).toArray()) {
+ await this.duplicateElement(element);
+ }
+ }
+
+ async pasteElements($before: any = null): Promise {
+ 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 {
+ 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 {
+ for (const element of $(elements).toArray()) {
+ await this.deleteElement(element);
+ }
+ }
+
+ // --- Card rendering ---------------------------------------------------------
+
+ async addElementCard(element: any): Promise {
+ return await this.addElementCards([element]);
+ }
+
+ async addElementCards(elements: any[], $before: any = null): Promise {
+ 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: {
+ // `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',
+ 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 = $('');
+ 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) {
+ // 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
+ $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);
+ }
+ });
+ }
+
+ // 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(
+ `craft-action-menu [${selector}]`
+ );
+ if (item) {
+ item.addEventListener('click', handler, options);
+ this.#disposers.push(() =>
+ item.removeEventListener('click', handler, options)
+ );
+ }
+ return item;
+ };
+
+ wireItem('data-move-forward-action', () => {
+ const li = element.closest('li');
+ const prev = li?.previousElementSibling;
+ if (li && prev) {
+ prev.before(li);
+ this.onSortChange($(li));
+ }
+ });
+
+ wireItem('data-move-backward-action', () => {
+ const li = element.closest('li');
+ const next = li?.nextElementSibling;
+ if (li && next) {
+ next.after(li);
+ this.onSortChange($(li));
+ }
+ });
+
+ wireItem('data-duplicate-action', () => {
+ if (!this.canCreate()) {
+ return;
+ }
+ if (this.bulkActionMode(element)) {
+ this.duplicateElements(this.elementSelect!.getSelectedItems());
+ } else {
+ this.duplicateElement(element);
+ }
+ });
+
+ // 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}));
+ }
+ },
+ {capture: true}
+ );
+
+ 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);
+ }
+ });
+
+ // 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: '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());
+ }
+ },
+ },
+ ]);
+ }
+
+ // Items are in place (paste injection resolves async) — sync their
+ // visibility/labels against the current state.
+ setTimeout(() => this.#syncCardActionItems());
+ }, 1);
+ }
+
+ /** The Paste item label for the current clipboard contents. */
+ #pasteItemLabel(copiedElements: any[]): string {
+ const nameIndex = copiedElements.length === 1 ? 2 : 3;
+
+ 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),
+ });
+ }
+
+ /**
+ * 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;
+ }
+
+ 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);
+
+ for (const li of Array.from(list.children)) {
+ const item = (selector: string) =>
+ li.querySelector(`craft-action-menu [${selector}]`);
+
+ const forward = item('data-move-forward-action');
+ if (forward) {
+ forward.hidden = !li.previousElementSibling;
+ }
+
+ const backward = item('data-move-backward-action');
+ if (backward) {
+ backward.hidden = !li.nextElementSibling;
+ }
+
+ const duplicate = item('data-duplicate-action');
+ if (duplicate) {
+ duplicate.hidden = !canCreate;
+ }
+
+ 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 {
+ 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 = [];
+ for (const dispose of this.#disposers) {
+ dispose();
+ }
+ this.#disposers = [];
+ 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 ``
+ * 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/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 {
interface UseSettingsSaveOptions> {
transform?: (data: T) => Record;
passwordConfirmation?: PasswordConfirmationOptions;
+ /**
+ * 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 | '*';
}
export function useSettingsSave>(
@@ -24,6 +32,13 @@ export function useSettingsSave>(
}>();
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>(
.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>(
.require({
force: true,
minimumRemainingSeconds:
- options.passwordConfirmation?.minimumRemainingSeconds,
+ passwordConfirmation.minimumRemainingSeconds,
})
.then((confirmed) => {
if (confirmed) {
@@ -89,11 +100,10 @@ export function useSettingsSave>(
});
}
- 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>(
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>(
+ form: InertiaForm,
+ fields: Array | '*' | undefined
+): PasswordConfirmationOptions | undefined {
+ if (!fields) {
+ return undefined;
+ }
+
+ if (fields === '*') {
+ return {required: () => form.isDirty};
+ }
+
+ const baseline = new Map(
+ 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/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/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)` → ``
+- `createSubmitButton(config)` → accent submit ``
+- `createPasteButton(config)` → "Paste elements" ``
+
+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 `` (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 `