@elementor/editor-elements 4.3.0-974 → 4.3.0-975

package/src/children-dependencies/bind-settings-reconcile.ts

@@ -0,0 +1,148 @@
+import { type PropValue } from '@elementor/editor-props';
+
+import { getContainer } from '../sync/get-container';
+import { addModelToParent, removeModelFromParent } from '../sync/resolve-element';
+import { resolveInsertIndex } from '../sync/resolve-insert-index';
+import { type V1Element, type V1ElementConfig, type V1ElementData, type V1ElementModelProps } from '../sync/types';
+import { createChildrenStash } from './stash';
+import { type ChildDependencyRule, type ChildrenStash } from './types';
+import { evaluateWhen } from './utils';
+
+type SettingsChangeSource = {
+	get: ( key: string ) => unknown;
+	toJSON: () => Record< string, PropValue >;
+	on?: ( event: string, callback: ( ...args: unknown[] ) => void ) => void;
+	off?: ( event: string, callback: ( ...args: unknown[] ) => void ) => void;
+};
+
+type ReactiveModel = {
+	get: ( key: string ) => unknown;
+};
+
+type BindSettingsReconcileArgs = {
+	model: ReactiveModel;
+	elementConfig: V1ElementConfig | undefined;
+};
+
+type Detach = () => void;
+
+export function bindSettingsReconcile( { model, elementConfig }: BindSettingsReconcileArgs ): Detach {
+	const stash = createChildrenStash();
+	const rules = elementConfig?.children_dependencies;
+
+	if ( ! rules?.length ) {
+		return () => {};
+	}
+
+	const settingsModel = model.get( 'settings' ) as SettingsChangeSource | undefined;
+	const elementId = model.get( 'id' ) as string | undefined;
+
+	if ( ! settingsModel?.on || ! settingsModel?.off || ! elementId ) {
+		return () => {};
+	}
+
+	const lastMet = new Map< string, boolean >();
+
+	rules.forEach( ( rule ) => {
+		lastMet.set( rule.child_type, evaluateWhen( rule.when, settingsModel.toJSON() ) );
+	} );
+
+	const onChange = () => {
+		const currentSettings = settingsModel.toJSON();
+
+		rules.forEach( ( rule ) => {
+			const previous = lastMet.get( rule.child_type ) ?? false;
+			const current = evaluateWhen( rule.when, currentSettings );
+
+			if ( previous === current ) {
+				return;
+			}
+
+			lastMet.set( rule.child_type, current );
+
+			if ( current ) {
+				attachChildFromRule( elementId, rule, stash );
+			} else {
+				detachChildFromRule( elementId, rule, stash );
+			}
+		} );
+	};
+
+	settingsModel.on( 'change', onChange );
+
+	return () => {
+		settingsModel.off?.( 'change', onChange );
+		stash.clearAllForElement( elementId );
+	};
+}
+
+function attachChildFromRule( parentId: string, rule: ChildDependencyRule, stash: ChildrenStash ): void {
+	const parent = getContainer( parentId ) ?? undefined;
+	const currentChildren = getDirectChildData( parent );
+	const alreadyPresent = currentChildren.some( ( child ) => child.elType === rule.child_type );
+
+	if ( alreadyPresent ) {
+		return;
+	}
+
+	const stashed = rule.stash ? stash.get( parentId, rule.child_type ) : undefined;
+	const modelData = stashed ?? rule.default_model ?? ( { elType: rule.child_type } as V1ElementData );
+	const insertAt = resolveInsertIndex( rule.position, currentChildren );
+
+	const attached = addModelToParent( parentId, modelData as unknown as V1ElementModelProps, { at: insertAt } );
+
+	if ( ! attached ) {
+		return;
+	}
+
+	if ( stashed ) {
+		stash.clear( parentId, rule.child_type );
+	}
+
+	requestNavigatorRefresh( parentId );
+}
+
+function detachChildFromRule( parentId: string, rule: ChildDependencyRule, stash: ChildrenStash ): void {
+	const parent = getContainer( parentId ) ?? undefined;
+	const child = parent?.children?.find( ( candidate ) => candidate.model.get( 'elType' ) === rule.child_type );
+
+	if ( ! child ) {
+		return;
+	}
+
+	const childSnapshot = child.model.toJSON() as unknown as V1ElementData;
+	const removed = removeModelFromParent( parentId, child.id );
+
+	if ( ! removed ) {
+		return;
+	}
+
+	if ( rule.stash ) {
+		stash.save( parentId, rule.child_type, childSnapshot );
+	}
+
+	requestNavigatorRefresh( parentId );
+}
+
+// Backbone `add`/`remove` on the parent elements collection is silent (see
+// assets/dev/js/editor/document/component.js addModelToParent / removeModelFromParent),
+// so the Marionette Navigator CompositeView never observes our mutation. The
+// legacy navigator exposes an `elementor/navigator/refresh-children` custom
+// window event (assets/dev/js/editor/regions/navigator/element.js) that
+// re-renders the subtree for a given element id — dispatch it here so the
+// Structure panel stays in sync with the model.
+function requestNavigatorRefresh( parentId: string ): void {
+	if ( typeof window === 'undefined' || typeof window.dispatchEvent !== 'function' ) {
+		return;
+	}
+
+	window.dispatchEvent(
+		new CustomEvent( 'elementor/navigator/refresh-children', {
+			detail: { elementId: parentId },
+		} )
+	);
+}
+
+function getDirectChildData( parent: V1Element | undefined ): V1ElementData[] {
+	return ( parent?.children ?? [] ).map( ( child ) => child.model.toJSON() as unknown as V1ElementData );
+}

package/src/children-dependencies/index.ts

@@ -0,0 +1,4 @@
+export { bindSettingsReconcile } from './bind-settings-reconcile';
+export { evaluateWhen } from './utils';
+export { reconcileInitialChildren } from './reconcile-initial-children';
+export type { ChildDependenciesConfig, ChildDependencyRule } from './types';

package/src/children-dependencies/reconcile-initial-children.ts

@@ -0,0 +1,60 @@
+import { resolveInsertIndex } from '../sync/resolve-insert-index';
+import { type V1ElementConfig, type V1ElementData, type V1ElementSettingsProps } from '../sync/types';
+import { createChildrenStash } from './stash';
+import { type ChildDependencyRule } from './types';
+import { evaluateWhen } from './utils';
+
+type ReconcileInitialChildrenArgs = {
+	elementId: string;
+	elementConfig: V1ElementConfig | undefined;
+	attributes: {
+		elements?: V1ElementData[];
+		settings?: V1ElementSettingsProps;
+	};
+};
+
+export function reconcileInitialChildren( {
+	elementId,
+	elementConfig,
+	attributes,
+}: ReconcileInitialChildrenArgs ): void {
+	const stash = createChildrenStash();
+	const rules = elementConfig?.children_dependencies;
+
+	if ( ! rules?.length ) {
+		return;
+	}
+
+	const elements = [ ...( attributes.elements ?? [] ) ];
+	const settings = attributes.settings ?? {};
+
+	rules.forEach( ( rule: ChildDependencyRule ) => {
+		const isMet = evaluateWhen( rule.when, settings );
+		const existingIndex = elements.findIndex( ( element ) => element.elType === rule.child_type );
+		const isPresent = existingIndex >= 0;
+
+		if ( isMet && ! isPresent ) {
+			const stashed = rule.stash ? stash.get( elementId, rule.child_type ) : undefined;
+			const modelData = stashed ?? rule.default_model ?? ( { elType: rule.child_type } as V1ElementData );
+			const insertAt = resolveInsertIndex( rule.position, elements );
+
+			elements.splice( insertAt, 0, modelData );
+
+			if ( stashed ) {
+				stash.clear( elementId, rule.child_type );
+			}
+
+			return;
+		}
+
+		if ( ! isMet && isPresent ) {
+			const [ removed ] = elements.splice( existingIndex, 1 );
+
+			if ( rule.stash && removed ) {
+				stash.save( elementId, rule.child_type, removed );
+			}
+		}
+	} );
+
+	attributes.elements = elements;
+}

package/src/children-dependencies/stash.ts

@@ -0,0 +1,40 @@
+import { getSessionStorageItem, removeSessionStorageItem, setSessionStorageItem } from '@elementor/session';
+
+import { type V1ElementData } from '../sync/types';
+import { type ChildrenStash } from './types';
+
+const STASH_KEY_PREFIX = 'elementor/editor-state';
+const STASH_KEY_SEGMENT = 'children-deps';
+
+export function createChildrenStash(): ChildrenStash {
+	return {
+		get( elementId, childType ) {
+			return getSessionStorageItem< V1ElementData >( buildStashKey( elementId, childType ) );
+		},
+		save( elementId, childType, data ) {
+			setSessionStorageItem( buildStashKey( elementId, childType ), data );
+		},
+		clear( elementId, childType ) {
+			removeSessionStorageItem( buildStashKey( elementId, childType ) );
+		},
+		clearAllForElement( elementId ) {
+			const prefix = buildElementStashPrefix( elementId );
+
+			for ( let index = sessionStorage.length - 1; index >= 0; index-- ) {
+				const key = sessionStorage.key( index );
+
+				if ( key?.startsWith( prefix ) ) {
+					removeSessionStorageItem( key );
+				}
+			}
+		},
+	};
+}
+
+function buildStashKey( elementId: string, childType: string ): string {
+	return `${ STASH_KEY_PREFIX }/${ elementId }/${ STASH_KEY_SEGMENT }/${ childType }`;
+}
+
+function buildElementStashPrefix( elementId: string ): string {
+	return `${ STASH_KEY_PREFIX }/${ elementId }/${ STASH_KEY_SEGMENT }/`;
+}

package/src/children-dependencies/types.ts

@@ -0,0 +1,20 @@
+import { type Dependency } from '@elementor/editor-props';
+
+import { type ElementPosition, type V1ElementData } from '../sync/types';
+
+export type ChildDependencyRule = {
+	child_type: string;
+	when: Dependency;
+	position: ElementPosition;
+	stash: boolean;
+	default_model: V1ElementData | null;
+};
+
+export type ChildDependenciesConfig = ChildDependencyRule[];
+
+export type ChildrenStash = {
+	get: ( elementId: string, childType: string ) => V1ElementData | undefined;
+	save: ( elementId: string, childType: string, data: V1ElementData ) => void;
+	clear: ( elementId: string, childType: string ) => void;
+	clearAllForElement: ( elementId: string ) => void;
+};

package/src/children-dependencies/utils.ts

@@ -0,0 +1,5 @@
+import { type Dependency, isDependencyMet, type PropValue } from '@elementor/editor-props';
+
+export function evaluateWhen( when: Dependency | undefined, settings: Record< string, PropValue > ): boolean {
+	return isDependencyMet( when, settings ).isMet;
+}

package/src/index.ts

@@ -2,6 +2,15 @@
 export * from './types';
 export type * from './sync/types';
 
+// children dependencies (schema-driven settings <-> children sync)
+export {
+	bindSettingsReconcile,
+	type ChildDependenciesConfig,
+	type ChildDependencyRule,
+	evaluateWhen,
+	reconcileInitialChildren,
+} from './children-dependencies';
+
 // hooks
 export { useElementChildren, type ElementChildren, type ElementModel } from './hooks/use-element-children';
 export { useElementEditorSettings } from './hooks/use-element-editor-settings';
@@ -46,6 +55,7 @@ export { moveElement, type MoveElementParams } from './sync/move-element';
 export { moveElements } from './sync/move-elements';
 export { removeElements } from './sync/remove-elements';
 export { replaceElement } from './sync/replace-element';
+export { resolveInsertIndex } from './sync/resolve-insert-index';
 export { updateElementEditorSettings } from './sync/update-element-editor-settings';
 export { updateElementSettings, type UpdateElementSettingsArgs } from './sync/update-element-settings';
 

package/src/sync/resolve-insert-index.ts

@@ -0,0 +1,34 @@
+import { type ElementPosition, type V1ElementData } from './types';
+
+export function resolveInsertIndex( position: ElementPosition, elements: V1ElementData[] ): number {
+	const lastIndex = elements.length;
+
+	switch ( position.kind ) {
+		case 'first':
+			return 0;
+
+		case 'last':
+			return lastIndex;
+
+		case 'index': {
+			const index = typeof position.value === 'number' ? position.value : lastIndex;
+
+			return Math.max( 0, Math.min( index, lastIndex ) );
+		}
+
+		case 'after_type': {
+			const anchor = elements.findIndex( ( element ) => element.elType === position.value );
+
+			return anchor >= 0 ? anchor + 1 : lastIndex;
+		}
+
+		case 'before_type': {
+			const anchor = elements.findIndex( ( element ) => element.elType === position.value );
+
+			return anchor >= 0 ? anchor : lastIndex;
+		}
+
+		default:
+			return lastIndex;
+	}
+}

package/src/sync/types.ts

@@ -1,6 +1,7 @@
 import { type PropsSchema, type PropValue, type SizePropValue } from '@elementor/editor-props';
 import { type ClassState, type StyleDefinition, type StyleDefinitionID } from '@elementor/editor-styles';
 
+import { type ChildDependencyRule } from '../children-dependencies/types';
 import { type ControlItem, type PseudoState } from '../types';
 
 export type ExtendedWindow = Window & {
@@ -168,6 +169,13 @@ export type V1ElementData = Omit< V1ElementModelProps, 'elements' > & {
 	elements?: V1ElementData[];
 };
 
+export type ElementPositionKind = 'last' | 'first' | 'index' | 'after_type' | 'before_type';
+
+export type ElementPosition = {
+	kind: ElementPositionKind;
+	value: number | string | null;
+};
+
 export type V1ElementEditorSettingsProps = {
 	title?: string;
 	initial_position?: number;
@@ -197,6 +205,7 @@ export type V1ElementConfig< T = object, TChild = unknown > = {
 	show_in_panel?: boolean;
 	allowed_child_types?: string[];
 	default_children?: Array< Record< string, TChild > >;
+	children_dependencies?: ChildDependencyRule[];
 	meta?: { [ key: string ]: string | number | boolean | null | NonNullable< V1ElementConfig[ 'meta' ] > };
 } & T;
 
@@ -205,4 +214,6 @@ type V1Model< T > = {
 	set: < K extends keyof T >( key: K, value: T[ K ] ) => void;
 	toJSON: ( options?: { remove?: string[] } ) => T;
 	trigger?: ( event: string, ...args: unknown[] ) => void;
+	on?: ( event: string, callback: ( ...args: unknown[] ) => void, context?: unknown ) => void;
+	off?: ( event: string, callback?: ( ...args: unknown[] ) => void, context?: unknown ) => void;
 };