PopupMaker · danieliser · Sep 23, 2026 · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+**Developers**
+
+-   Improved Call to Action field schema support for add-ons.
+
 ## v1.25.0 - 2026-09-10
 
 **Security**

diff --git a/packages/components/src/lib/smart-token-control/editor.scss b/packages/components/src/lib/smart-token-control/editor.scss
@@ -2,11 +2,14 @@
 	width: 100%;
 
 	.component-smart-token-control__input {
-		padding: 5px;
+		align-items: center;
+		box-sizing: border-box;
+		min-height: 40px;
+		padding: 4px 8px;
 		box-shadow: 0 0 0 transparent;
-		border-radius: 4px;
+		border-radius: 2px;
 		border: 1px solid #8c8f94;
-		margin: 0 1px;
+		margin: 0;
 		display: flex;
 		flex-wrap: wrap;
 		justify-content: space-between;
@@ -58,8 +61,8 @@
 			padding: 0;
 			margin: 0;
 			width: 100%;
-			line-height: 1.2;
-			min-height: auto;
+			line-height: 1.4;
+			min-height: 30px;
 			cursor: pointer;
 		}
 
@@ -76,6 +79,12 @@
 			margin: 0;
 		}
 	}
+
+	&.is-focused .component-smart-token-control__input {
+		border-color: var(--wp-admin-theme-color);
+		box-shadow: 0 0 0 1px var(--wp-admin-theme-color);
+		outline: 2px solid transparent;
+	}
 }
 
 .component-smart-token-control__suggestions {

diff --git a/packages/core-data/src/call-to-actions/actions.ts b/packages/core-data/src/call-to-actions/actions.ts
@@ -4,6 +4,7 @@ import { compare as jsonpatchCompare } from 'fast-json-patch';
 import { __, sprintf } from '@popup-maker/i18n';
 import { store as noticesStore } from '@wordpress/notices';
 import { decodeEntities } from '@wordpress/html-entities';
+import { applyFilters } from '@wordpress/hooks';
 
 import { ACTION_TYPES, NOTICE_CONTEXT } from './constants';
 
@@ -35,6 +36,12 @@ const {
 	INVALIDATE_RESOLUTION,
 } = ACTION_TYPES;
 
+/** Apply editor-provided normalization immediately before validation and I/O. */
+const prepareCallToActionForSave = < T extends Partial< EditableCta > >(
+	callToAction: T
+): T =>
+	applyFilters( 'popupMaker.callToAction.prepareForSave', callToAction ) as T;
+
 /**
  * Helper function to handle field-specific validation errors using WordPress notices
  *
@@ -134,9 +141,9 @@ const entityActions = {
 	/**
 	 * Create a new entity record. Values sent to the server immediately.
 	 *
-	 * @param {Editable} callToAction The entity to create.
-	 * @param {boolean}  validate     An optional validation function.
-	 * @param {boolean}  withNotices  Whether to show notices.
+	 * @param {Partial<EditableCta>} callToAction The entity to create.
+	 * @param {boolean}              validate     An optional validation function.
+	 * @param {boolean}              withNotices  Whether to show notices.
 	 * @return {Promise<CallToAction< 'edit' > | false>} The created entity or false if validation fails.
 	 */
 	createCallToAction:
@@ -157,7 +164,8 @@ const entityActions = {
 					},
 				} );
 
-				const { id, ...newCta } = callToAction;
+				const { id, ...rawCta } = callToAction;
+				const newCta = prepareCallToActionForSave( rawCta );
 
 				if ( validate ) {
 					const validation = validateCallToAction( newCta );
@@ -281,18 +289,24 @@ const entityActions = {
 	 * @param {PartialEditableCta} callToAction The entity to update.
 	 * @param {boolean}            validate     An optional validation function.
 	 * @param {boolean}            withNotices  Whether to show notices.
-	 * @return {Promise<T | boolean>} The updated entity or false if validation fails.
+	 * @param {boolean}            prepare      Whether to run save preparation.
+	 * @return {Promise<CallToAction<'edit'> | false>} The updated entity or false if validation fails.
 	 */
 	updateCallToAction:
 		(
 			callToAction: PartialEditableCta,
 			validate: boolean = true,
-			withNotices: boolean = true
+			withNotices: boolean = true,
+			prepare: boolean = true
 		): ThunkAction< CallToAction< 'edit' > | false > =>
 		async ( { select, dispatch, registry } ) => {
 			const action = 'updateCallToAction';
 
 			try {
+				const preparedCallToAction = prepare
+					? prepareCallToActionForSave( callToAction )
+					: callToAction;
+
 				dispatch( {
 					type: CHANGE_ACTION_STATUS,
 					payload: {
@@ -302,7 +316,8 @@ const entityActions = {
 				} );
 
 				if ( validate ) {
-					const validation = validateCallToAction( callToAction );
+					const validation =
+						validateCallToAction( preparedCallToAction );
 
 					if ( true !== validation ) {
 						dispatch( {
@@ -328,7 +343,7 @@ const entityActions = {
 				}
 
 				const canonicalCallToAction = await select.getCallToAction(
-					callToAction.id
+					preparedCallToAction.id
 				);
 
 				if ( ! canonicalCallToAction ) {
@@ -366,7 +381,7 @@ const entityActions = {
 					`ctas/${ canonicalCallToAction.id }`,
 					{
 						method: 'POST',
-						data: callToAction,
+						data: preparedCallToAction,
 					}
 				);
 
@@ -726,10 +741,12 @@ const editorActions = {
 
 					return false;
 				}
+				const preparedCallToAction =
+					prepareCallToActionForSave( editedCallToAction );
 
-				if ( editedCallToAction && validate ) {
+				if ( preparedCallToAction && validate ) {
 					const validation =
-						validateCallToAction( editedCallToAction );
+						validateCallToAction( preparedCallToAction );
 
 					if ( true !== validation ) {
 						registry.batch( async () => {
@@ -757,9 +774,10 @@ const editorActions = {
 				}
 
 				const result = await dispatch.updateCallToAction(
-					editedCallToAction,
+					preparedCallToAction,
 					false,
-					withNotices
+					withNotices,
+					false
 				);
 
 				if ( result ) {
@@ -1023,7 +1041,7 @@ const editorActions = {
 	 * Opens the editor immediately. If the entity isn't in the store yet it is
 	 * resolved in the background while consumers render a loading state.
 	 *
-	 * @param {EditorId} editorId The editor ID.
+	 * @param {CtaEditorId} editorId The editor ID.
 	 * @return {Promise<void>}
 	 */
 	changeEditorId:
@@ -1284,9 +1302,9 @@ const resolutionActions = {
 	/**
 	 * Change status of a dispatch action request.
 	 *
-	 * @param {CallToActionsStore[ 'ActionNames' ]} actionName Action name to change status of.
-	 * @param {Statuses}                            status     New status.
-	 * @param {string|undefined}                    message    Optional error message.
+	 * @param {string}           actionName Action name to change status of.
+	 * @param {DispatchStatus}   status     New status.
+	 * @param {string|undefined} message    Optional error message.
 	 * @return {Object} Action object.
 	 */
 	changeActionStatus:

diff --git a/packages/cta-editor/src/components/field-with-error.tsx b/packages/cta-editor/src/components/field-with-error.tsx
@@ -3,12 +3,16 @@ import { Field } from '@popup-maker/fields';
 import { URLControl } from '@popup-maker/components';
 import { FieldWrapper } from './field-wrapper';
 import { useFieldError } from '../hooks';
+import {
+	getFieldDefault,
+	normalizeFieldDefault,
+} from '../registries/fields/field-visibility';
 
-import type { FieldProps } from '@popup-maker/fields';
+import type { FieldProps, OldFieldBase } from '@popup-maker/fields';
 
 interface FieldWithErrorProps {
 	fieldId: string;
-	field: FieldProps;
+	field: FieldProps & { errorFieldIds?: string[] };
 	value: any;
 	onChange: ( value: any ) => void;
 }
@@ -29,7 +33,10 @@ export const FieldWithError: React.FC< FieldWithErrorProps > = ( {
 	value,
 	onChange,
 } ) => {
-	const { error, clearError } = useFieldError( fieldId );
+	const { error, clearError } = useFieldError(
+		fieldId,
+		field.errorFieldIds ?? []
+	);
 
 	// Clear field error when value changes
 	const handleChange = ( newValue: any ) => {
@@ -40,21 +47,57 @@ export const FieldWithError: React.FC< FieldWithErrorProps > = ( {
 		onChange( newValue );
 	};
 
+	const legacyDescription = (
+		field as FieldProps & Pick< OldFieldBase, 'desc' >
+	 ).desc;
+	const { heading: _heading, help, description, ...controlField } = field;
+	const effectiveValue =
+		value ?? normalizeFieldDefault( getFieldDefault( field ), field );
+	const fieldHelp = help ?? description ?? legacyDescription;
+	const needsExternalHelp = [
+		'color',
+		'html',
+		'multicheck',
+		'rangeslider',
+		'tokenselect',
+	].includes( field.type );
+	const fieldControl =
+		field.type === 'url' ? (
+			<>
+				<URLControl
+					{ ...controlField }
+					value={ effectiveValue }
+					onChange={ ( urlValue ) => handleChange( urlValue.url ) }
+				/>
+				{ fieldHelp && (
+					<p className="components-base-control__help">
+						{ fieldHelp }
+					</p>
+				) }
+			</>
+		) : (
+			<>
+				<Field
+					{ ...controlField }
+					help={ fieldHelp }
+					description={ description }
+					value={ effectiveValue }
+					onChange={ handleChange }
+				/>
+				{ needsExternalHelp && fieldHelp && (
+					<p className="components-base-control__help">
+						{ fieldHelp }
+					</p>
+				) }
+			</>
+		);
 	return (
 		<FieldWrapper
 			fieldId={ fieldId }
-			title={ field.label ?? '' }
+			title={ field.heading ?? field.label ?? '' }
 			error={ error }
 		>
-			{ field.type === 'url' ? (
-				<URLControl
-					{ ...field }
-					value={ value }
-					onChange={ ( urlValue ) => handleChange( urlValue.url ) }
-				/>
-			) : (
-				<Field { ...field } value={ value } onChange={ handleChange } />
-			) }
+			{ fieldControl }
 		</FieldWrapper>
 	);
 };

diff --git a/packages/cta-editor/src/editor/editor.scss b/packages/cta-editor/src/editor/editor.scss
@@ -96,7 +96,7 @@ $gap4: $gap * 4;
 			svg {
 				margin-right: 3px;
 				fill: #fff;
-				stroke: green;
+				stroke: #008000;
 			}
 		}
 	}
@@ -114,6 +114,11 @@ $gap4: $gap * 4;
 				&.is-active {
 					background-color: #f0f0f0;
 				}
+
+				&.error {
+					background-color: #f4a2a2;
+					border-left: 4px solid #cc1818;
+				}
 			}
 		}
 
@@ -204,7 +209,7 @@ $gap4: $gap * 4;
 					}
 
 					&:not(:focus) {
-						box-shadow: inset 0 0 0 2px #dddddd;
+						box-shadow: inset 0 0 0 2px #ddd;
 					}
 				}
 			}
@@ -322,15 +327,10 @@ $gap4: $gap * 4;
 		}
 	}
 
-	.editor-tabs {
-		.components-tab-panel__tabs {
-			.components-tab-panel__tabs-item {
-				&.error {
-					background-color: #f4a2a2;
-					border-left: 4px solid #cc1818;
-				}
-			}
-		}
+	.pum-field__selected-help {
+		border-left: 2px solid #ddd;
+		margin-top: 8px;
+		padding-left: 10px;
 	}
 
 	// Loading placeholder layout while the record resolves.

diff --git a/packages/cta-editor/src/editor/hocs/with-modal.tsx b/packages/cta-editor/src/editor/hocs/with-modal.tsx
@@ -59,6 +59,7 @@ export const withModal = (
 		closeOnSave = true,
 		showDocumentationLink = true,
 		showActions = true,
+		onSave,
 		onClose,
 		// @ts-ignore It exists but is not typed.
 		onRequestClose,
@@ -193,8 +194,11 @@ export const withModal = (
 						return;
 					}
 
-					// Call the onSave callback if it exists
-					componentProps?.onSave?.( values );
+					// Read the canonical record after save preparation and persistence.
+					const savedValues = storeSelectors.getCurrentEditorValues();
+					if ( savedValues ) {
+						onSave?.( savedValues );
+					}
 
 					const hasRemainingEdits = storeSelectors.hasEdits(
 						values.id
@@ -209,7 +213,14 @@ export const withModal = (
 				}
 			},
 			// eslint-disable-next-line react-hooks/exhaustive-deps
-			[ closeOnSave, closeModal, storeSelectors, hasAnyError, values ]
+			[
+				closeOnSave,
+				closeModal,
+				storeSelectors,
+				hasAnyError,
+				onSave,
+				values,
+			]
 		);
 
 		return (