@elementor/editor-elements 4.2.0-beta2 → 4.3.0-1000

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,59 @@
+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, resolveChildModelData } 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 { modelData, wasStashed } = resolveChildModelData( elementId, rule, stash );
+			const insertAt = resolveInsertIndex( rule.position, elements );
+
+			elements.splice( insertAt, 0, modelData );
+
+			if ( wasStashed ) {
+				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,44 @@
+import { type Dependency, isDependencyMet, type PropValue } from '@elementor/editor-props';
+
+import { generateElementId } from '../sync/generate-element-id';
+import { type V1ElementData } from '../sync/types';
+import { type ChildDependencyRule, type ChildrenStash } from './types';
+
+export function evaluateWhen( when: Dependency | undefined, settings: Record< string, PropValue > ): boolean {
+	return isDependencyMet( when, settings ).isMet;
+}
+
+export function ensureModelId( model: V1ElementData ): V1ElementData {
+	const { skipDefaultChildren: _skipDefaultChildren, ...rest } = model;
+
+	return rest.id ? rest : { ...rest, id: generateElementId() };
+}
+
+type ResolvedChildModel = {
+	modelData: V1ElementData;
+	wasStashed: boolean;
+};
+
+/**
+ * Resolve the model to attach for a child-dependency rule, preferring a previously-stashed
+ * (user-customized) model, then the rule's default, else a bare element.
+ *
+ * `default_model` and the bare fallback never carry an id, so they're run through
+ * `ensureModelId` before the model reaches Backbone.
+ *
+ * @param elementId Parent element id, used as the stash lookup key.
+ * @param rule      The child-dependency rule being resolved.
+ * @param stash     Session-backed stash for previously-detached child models.
+ */
+export function resolveChildModelData(
+	elementId: string,
+	rule: ChildDependencyRule,
+	stash: ChildrenStash
+): ResolvedChildModel {
+	const stashed = rule.stash ? stash.get( elementId, rule.child_type ) : undefined;
+	const modelData = ensureModelId(
+		stashed ?? rule.default_model ?? ( { elType: rule.child_type } as V1ElementData )
+	);
+
+	return { modelData, wasStashed: Boolean( stashed ) };
+}

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';
@@ -27,7 +36,9 @@ export { addModelToParent, findModelInDocument, removeModelFromParent, resolveCo
 export { getCurrentDocumentContainer } from './sync/get-current-document-container';
 export { getCurrentDocumentId } from './sync/get-current-document-id';
 export { getElementEditorSettings } from './sync/get-element-editor-settings';
+export { getElementIcon } from './sync/get-element-icon';
 export { getElementLabel } from './sync/get-element-label';
+export { getElementTitle } from './sync/get-element-title';
 export { getElementSetting, getElementSettings } from './sync/get-element-setting';
 export { getElementStyles } from './sync/get-element-styles';
 export { getElementType } from './sync/get-element-type';
@@ -44,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/get-element-icon.ts

@@ -0,0 +1,14 @@
+import { type ElementID } from '../types';
+import { getContainer } from './get-container';
+import { getWidgetsCache } from './get-widgets-cache';
+
+export function getElementIcon( elementId: ElementID ): string | null {
+	const container = getContainer( elementId );
+	const type = container?.model.get( 'widgetType' ) || container?.model.get( 'elType' );
+
+	if ( ! type ) {
+		return null;
+	}
+
+	return getWidgetsCache()?.[ type ]?.icon ?? null;
+}

package/src/sync/get-element-title.ts

@@ -0,0 +1,48 @@
+import { type ElementID } from '../types';
+import { getElementEditorSettings } from './get-element-editor-settings';
+import { getElementLabel } from './get-element-label';
+import { getElementSetting } from './get-element-setting';
+
+function extractString( value: unknown ): string | null {
+	if ( typeof value === 'string' ) {
+		return value || null;
+	}
+
+	if (
+		value &&
+		typeof value === 'object' &&
+		'value' in value &&
+		typeof ( value as { value: unknown } ).value === 'string'
+	) {
+		return ( value as { value: string } ).value || null;
+	}
+
+	return null;
+}
+
+export function getElementTitle( elementId: ElementID ): string | null {
+	const editorSettings = getElementEditorSettings( elementId );
+	const editorTitle = extractString( editorSettings?.title );
+
+	if ( editorTitle ) {
+		return editorTitle;
+	}
+
+	const legacyTitle = extractString( getElementSetting( elementId, '_title' ) );
+
+	if ( legacyTitle ) {
+		return legacyTitle;
+	}
+
+	const presetTitle = extractString( getElementSetting( elementId, 'presetTitle' ) );
+
+	if ( presetTitle ) {
+		return presetTitle;
+	}
+
+	try {
+		return getElementLabel( elementId );
+	} catch {
+		return null;
+	}
+}

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 & {
@@ -162,12 +163,20 @@ export type V1ElementModelProps = {
 	interactions?: string | ElementInteractions;
 	isGlobal?: boolean;
 	skipDefaultChildren?: boolean;
+	hydrateDefaultChildren?: boolean;
 };
 
 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 +206,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 +215,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;
 };