@plaudit/gutenberg-api-extensions 2.79.0 → 2.80.0

package/src/blocks/simple-native-property-impl.tsx

@@ -0,0 +1,329 @@
+import {createHigherOrderComponent} from "@wordpress/compose";
+import {dispatch, select} from "@wordpress/data";
+import {useEffect, useMemo} from "@wordpress/element";
+import {addAction, addFilter} from "@wordpress/hooks";
+
+import {produce} from "immer";
+
+import {useDataController, walkToNodeInValue} from "./data-controller";
+import {DataControllerManager, createDataControllerManager} from "./data-controller-manager";
+import {extractStyleLayerValueFromAttributes, LayeredStylesDataStore} from "./layered-styles-impl";
+import {TabsRoot} from "./layout/TabsRoot";
+import {PanelRoot} from "./layout/PanelRoot";
+import {ActualBEPAttrs, ActualBlockEditProps, ActualBlockListBlockProps, isBlockJsonNativePropsConfig, RegisterBlockAttrs} from "../lib/useful-types";
+import {PathError} from "./PathError";
+import type {DataController, DataStore, HydratedSimpleNativeProperty, InspectorPanelGroup} from "./simple-native-property-api";
+import type {HydratedSimpleNativePanel, PerBlockExtraPropTransforms, PreppedSimpleNativePanelsAndTabs} from "./simple-native-property-internal-shared";
+import {SNPDataStore} from "./snp-data-store";
+import {SNPTreeContext} from "./SNPTreeContext";
+
+class AttributeDataStore extends SNPDataStore {
+	public getAttribute(name: string): any {
+		return this.blockEditProps.attributes[name];
+	}
+
+	public setAttribute(name: string, value: any) {
+		this.blockEditProps.setAttributes(name === 'className' ? {className: value?.toString()} : {[name]: value});
+	}
+}
+
+type ActualBlockSaveProps = {[key: Exclude<string, 'className'|'style'>]: unknown|undefined, className?: string|undefined, style?: Record<string, unknown>};
+
+export function installSimpleNativePropertiesSupport() {
+	if (installSimpleNativePropertiesSupport.called) {
+		return;
+	}
+	installSimpleNativePropertiesSupport.called = true;
+
+	const dataControllerManager = createDataControllerManager();
+
+	const registeredBlocks = new Map<string, boolean>();
+	addFilter('blocks.registerBlockType', 'plaudit/gutenberg-api-extensions/simple-native-properties', (atts: RegisterBlockAttrs<Record<string, any>>) => {
+		let isPlauditNative: boolean;
+		if (registeredBlocks.has(atts.name)) {
+			isPlauditNative = registeredBlocks.get(atts.name)!;
+		} else {
+			dispatch('plaudit/gutenberg-api-extensions').recordBaselineBlockAttrs(atts);
+			if ((isPlauditNative = isBlockJsonNativePropsConfig(atts.plaudit)) && atts.plaudit.properties !== undefined
+				&& (Array.isArray(atts.plaudit.properties) ? atts.plaudit.properties.length : atts.plaudit.properties)
+			) {
+				dispatch('plaudit/gutenberg-api-extensions').addProperties(atts.name, atts.plaudit.properties);
+			}
+			registeredBlocks.set(atts.name, isPlauditNative);
+		}
+		//TODO: Figure out some way to re-register a block when its attributes are changed
+		const blockSimpleNativePanelsAndTabs = select('plaudit/gutenberg-api-extensions').preppedProperties(atts.name);
+		if (blockSimpleNativePanelsAndTabs) {
+			const extraPropTransforms = select('plaudit/gutenberg-api-extensions').extraPropTransforms(atts.name) ?? {};
+			const attsAttributes = {...atts.attributes};
+			if (isPlauditNative && Object.values(extraPropTransforms).some(cfg => cfg.styleProperty)) {
+				attsAttributes['__plaudit/computed-style-attr'] = {type: "object"};
+			}
+			const injectableProperties: Record<string, any> = {};
+			for (const panel of blockSimpleNativePanelsAndTabs.panels) {
+				attachSNPsInPanel(panel[1].properties, injectableProperties);
+			}
+			for (const tabGroup of Object.values(blockSimpleNativePanelsAndTabs.tabs)) {
+				for (const tab of Object.values(tabGroup[1])) {
+					for (const item of tab.items) {
+						if ('properties' in item) {
+							attachSNPsInPanel(item.properties, injectableProperties);
+						} else if (Array.isArray(item)) {
+							attachSNPsInPanel(item, injectableProperties);
+						} else {
+							attachSNP(item, injectableProperties);
+						}
+					}
+				}
+			}
+			for (const [name, config] of Object.entries(injectableProperties)) {
+				attsAttributes[name] = config;
+			}
+			return {...atts, attributes: attsAttributes};
+		}
+		return atts;
+	});
+
+	addFilter('editor.BlockEdit', 'plaudit/gutenberg-api-extensions/simple-native-properties',
+		createHigherOrderComponent(BlockEdit => (blockEditProps: ActualBlockEditProps) => {
+			const blockSimpleNativePanelsAndTabs = select('plaudit/gutenberg-api-extensions').preppedProperties(blockEditProps.name);
+			if (!blockSimpleNativePanelsAndTabs) {
+				return <BlockEdit {...blockEditProps} />;
+			}
+			const selectedEditor = select("core/block-editor");
+			if (selectedEditor.getBlockParentsByBlockName(blockEditProps.clientId, "core/block")?.length) {
+				// If we have a core/block ancestor, then we can't be edited and attempting to self-edit will cause a crash
+				return <BlockEdit {...blockEditProps} />;
+			}
+			return <DataControllerInitializationIsolator bep={blockEditProps} dcm={dataControllerManager} BlockEdit={BlockEdit} snpPanelsAndTabs={blockSimpleNativePanelsAndTabs} />;
+		}, 'plauditGutenbergApiExtensionsSimpleNativeProperties'));
+
+	addAction('plaudit.gutenbergApiExtensions.simpleNativeProperties.afterWrite', 'plaudit/gutenberg-api-extensions/simple-native-properties',
+		(value: unknown, definition: HydratedSimpleNativeProperty, dataStore: DataStore) => {
+			if ("styleProperty" in definition && definition.styleProperty) {
+				const computedStyleAttr: {[key: string]: { property: string, value: string, className: string }} = dataStore.getValue('__plaudit/computed-style-attr') ?? {};
+				const valueStr = value?.toString();
+				if (computedStyleAttr[definition.name]?.value !== valueStr) {
+					if (valueStr?.length) {
+						dataStore.setValue('__plaudit/computed-style-attr', {
+							...computedStyleAttr,
+							[definition.name]: {property: definition.styleProperty, value: valueStr, className: makeHasPropClassName(definition.name)}
+						});
+					} else {
+						const entries = Object.entries(computedStyleAttr)
+							.filter(([key]) => key !== definition.name);
+						dataStore.setValue('__plaudit/computed-style-attr', entries.length ? Object.fromEntries(entries) : undefined);
+					}
+				}
+			}
+		});
+
+	addFilter('editor.BlockListBlock', 'plaudit/gutenberg-api-extensions/simple-native-properties',
+		createHigherOrderComponent(BlockListBlock => (props: ActualBlockListBlockProps) => {
+			const wrapperProps: {className?: string, style?: Record<string, unknown>} = {...props.wrapperProps};
+			const extraPropTransforms = select('plaudit/gutenberg-api-extensions').computedExtraPropTransforms(props.name);
+			if (!extraPropTransforms || !extraPropTransforms.appliesInEditor) {
+				const dataController = dataControllerManager.getDataController(props.clientId);
+				if (!dataController) {
+					return <BlockListBlock {...props} />;
+				}
+
+				const hasValidationError = dataController.hasValidationErrors();
+				dataControllerManager.notifyOfValidationErrorStatusChange(props.clientId, hasValidationError);
+				dataController.dispatch({type: "checkConditions"}); // We don't want to wrap this in a useEffect because this function is already only called when necessary.
+
+				if (hasValidationError) {
+					//TODO: Should I set isValid?
+					wrapperProps.className = wrapperProps.className ? `${wrapperProps.className} has-validation-error` : "has-validation-error";
+					return <BlockListBlock {...props} wrapperProps={wrapperProps} />;
+				}
+				return <BlockListBlock {...props} />;
+			}
+
+			const dataController = dataControllerManager.getDataController(props.clientId);
+			if (!dataController) {
+				return <BlockListBlock
+					{...props}
+					wrapperProps={applyExtraPropTransforms(extraPropTransforms.transforms, props.attributes, wrapperProps)}
+				/>;
+			}
+
+			const hasValidationError = dataController.hasValidationErrors();
+			dataControllerManager.notifyOfValidationErrorStatusChange(props.clientId, hasValidationError);
+			dataController.dispatch({type: "checkConditions"}); // We don't want to wrap this in a useEffect because this function is already only called when necessary.
+
+			if (hasValidationError) {
+				//TODO: Should I set isValid?
+				wrapperProps.className = wrapperProps.className ? `${wrapperProps.className} has-validation-error` : "has-validation-error";
+			}
+			return (
+				<BlockListBlock
+					{...props}
+					wrapperProps={applyExtraPropTransforms(extraPropTransforms.transforms, props.attributes, wrapperProps)}
+				/>
+			);
+		}, 'plauditGutenbergApiExtensionsSimpleNativeWrapperMarkup'));
+
+	addFilter('blocks.getSaveContent.extraProps', 'plaudit/gutenberg-api-extensions/simple-native-properties',
+		(props: ActualBlockSaveProps, blockType: RegisterBlockAttrs, attributes: ActualBEPAttrs) => {
+			if (isBlockJsonNativePropsConfig(blockType.plaudit)) {
+				return props;
+			}
+			const extraPropTransforms = select('plaudit/gutenberg-api-extensions').computedExtraPropTransforms(blockType.name);
+
+			return extraPropTransforms && extraPropTransforms.appliesInEditor ? produce(props, draft => {
+				applyExtraPropTransforms(extraPropTransforms.transforms, attributes, draft);
+			}) : props;
+		});
+}
+export namespace installSimpleNativePropertiesSupport {
+	export let called: boolean = false;
+}
+
+type DataControllerInitializationIsolatorProps = {bep: ActualBlockEditProps, dcm: DataControllerManager, snpPanelsAndTabs: PreppedSimpleNativePanelsAndTabs, BlockEdit: any};
+function DataControllerInitializationIsolator({bep, dcm, snpPanelsAndTabs, BlockEdit}: DataControllerInitializationIsolatorProps) {
+	const dataController = useDataController(bep.clientId);
+	useEffect(() => {
+		dcm.addDataController(bep.clientId, dataController);
+		return () => dcm.removeDataController(bep.clientId);
+	}, [dataController, bep.clientId]);
+
+	return <>
+		<BlockEdit {...bep} />
+		<SNPPropsWrapper blockEditProps={bep} blockSimpleNativePanelsAndTabs={snpPanelsAndTabs} dataController={dataController} />
+	</>;
+}
+
+function applyExtraPropTransforms(
+	extraPropTransforms: PerBlockExtraPropTransforms['transforms'], attributes: ActualBEPAttrs, draft: {className?: string, style?: Record<string, unknown>}
+) {
+	for (const [propPath, propTransform] of extraPropTransforms) {
+		let value: any;
+		try {
+			value = propTransform.forLayeredStyles ? extractStyleLayerValueFromAttributes(attributes, propPath[0]) : walkToNodeInValue(attributes[propPath[0]], propPath);
+		} catch (e) {
+			if (e instanceof PathError) {
+				value = undefined;
+			} else {
+				console.error("Encountered an error while applying extra props transforms:", e);
+				continue;
+			}
+		}
+
+		if (propTransform.styleProperty) {
+			const hasPropNameClass = makeHasPropClassName(propTransform.propName);
+			if (typeof value === 'string' || typeof value === 'number') {
+				const styleValue = typeof value === 'number' ? value.toString() : value.trim();
+				if (styleValue.length) {
+					if (draft.style) {
+						draft.style[propTransform.styleProperty] = styleValue;
+					} else {
+						draft.style = {[propTransform.styleProperty]: styleValue};
+					}
+					if (!draft.className) {
+						draft.className = hasPropNameClass;
+					} else if (!draft.className.split(/\s+/).includes(hasPropNameClass)) {
+						draft.className = draft.className + " " + hasPropNameClass;
+					}
+				} else {
+					if (draft.style) {
+						delete draft.style[propTransform.styleProperty];
+					}
+					if (draft.className) {
+						draft.className = draft.className.split(/\s+/).filter(cn => cn !== hasPropNameClass).join(" ");
+					}
+				}
+			} else if (value === undefined || value === null) {
+				if (draft.style) {
+					delete draft.style[propTransform.styleProperty];
+				}
+				if (draft.className) {
+					draft.className = draft.className.split(/\s+/).filter(cn => cn !== hasPropNameClass).join(" ");
+				}
+			} else {
+				console.error(`Encountered a SNP that had a styleProperty set but evaluated to a ${typeof value}.`, "Prop path:", propPath.join("."));
+			}
+		}
+	}
+	return draft;
+}
+
+function makeDataStoreForPanelOrTab(blockEditProps: ActualBlockEditProps, group: string|undefined, attributeCache: Record<string, any>) {
+	return group === 'layered-styles' ? new LayeredStylesDataStore(blockEditProps, attributeCache) : new AttributeDataStore(blockEditProps, attributeCache);
+}
+type SNPPropsWrapperProps = {blockSimpleNativePanelsAndTabs: PreppedSimpleNativePanelsAndTabs, blockEditProps: ActualBlockEditProps, dataController: DataController};
+function SNPPropsWrapper({blockSimpleNativePanelsAndTabs, blockEditProps, dataController}: SNPPropsWrapperProps) {
+	useMemo(() => {
+		const attributeCache = Object.create(null);
+		for (const panel of blockSimpleNativePanelsAndTabs.panels) {
+			const dataStore = makeDataStoreForPanelOrTab(blockEditProps, panel[1].group, attributeCache);
+			dataController.addProperties(panel[1].properties, dataStore, true);
+		}
+		for (const [group, [_, tabs]] of Object.entries(blockSimpleNativePanelsAndTabs.tabs)) {
+			const dataStore = makeDataStoreForPanelOrTab(blockEditProps, group, attributeCache);
+			for (const tab of Object.values(tabs)) {
+				for (const panel of tab.items) {
+					dataController.addProperties(panel.properties, dataStore, true);
+				}
+			}
+		}
+		dataController.dispatch({type: "checkConditions"});
+		dataController.dispatch({type: "validateNodes"});
+		dataController.dispatch({type: "commitBatchAddedProperties"});
+	}, [blockSimpleNativePanelsAndTabs, dataController]); // We don't depend on blockEditProps here - that is handled by the following useEffect
+
+	// We have to reattach dataStores in the useMemo segment in order for Panel- and Tab-level conditions to work
+	useMemo(() => {
+		const attributeCache = Object.create(null);
+		for (const dataStore of dataController.getAllDataStores()) {
+			dataStore.reattach(blockEditProps, attributeCache);
+		}
+	}, [dataController.getAllDataStores(), blockEditProps]);
+
+	useEffect(() => {
+		//TODO: This is a temporary patch. The proper solution is to subscribe to the block-editor redux store and use that to determine when properties have changed.
+		if (dataController.getWasChangedByManagedControl()) {
+			dataController.markManagedControlChangeHandled();
+		} else{
+			dataController.dispatch({type: "checkConditions"});
+			dataController.dispatch({type: "validateNodes"});
+		}
+	}, [dataController.getAllDataStores(), blockEditProps]);
+
+	//TODO: Hook into block-focus change listener and run validation on focus change
+	return <SNPTreeContext.Provider value={dataController}>
+		{...blockSimpleNativePanelsAndTabs.panels.map(panel => <PanelRoot key={panel[0]} panel={panel[1]} />)}
+		{...Object.entries(blockSimpleNativePanelsAndTabs.tabs).map(
+			([group, tabs]) => <TabsRoot key={tabs[0]} tabs={tabs[1]} tabGroupName={group as InspectorPanelGroup} />)}
+	</SNPTreeContext.Provider>;
+}
+
+function attachSNP(property: HydratedSimpleNativeProperty, injectableProperties: Record<string, any>) {
+	injectableProperties[property.name] = {type: property.type, default: property.alwaysStore !== false ? undefined : property.default};
+	if ('enum' in property) {
+		injectableProperties[property.name].enum = property.enum;
+	}
+}
+
+function attachSNPsInPanel(properties: HydratedSimpleNativePanel['properties'], injectableProperties: Record<string, any>) {
+	for (const property of properties) {
+		if (Array.isArray(property)) {
+			for (const prop of property) {
+				attachSNP(prop, injectableProperties);
+			}
+		} else {
+			attachSNP(property, injectableProperties);
+		}
+	}
+}
+
+export function makeHasPropClassName(propName: string) {
+	return "has-" + kebabCase(propName);
+}
+const kebabCaseRegexes = [/([a-z])([A-Z])/g, /[\s_]+/g] as const;
+export function kebabCase(value: string) {
+	return value
+		.replace(kebabCaseRegexes[0], "$1-$2")
+		.replace(kebabCaseRegexes[1], '-')
+		.toLowerCase();
+}

package/src/blocks/simple-native-property-internal-shared.ts

@@ -0,0 +1,46 @@
+import type {HydratedSimpleNativeProperty, InspectorPanelGroup, SimpleNativePanel, SimpleNativeTab} from "./simple-native-property-api";
+
+export type ExtraPropTransformConfig = {propName: string, forLayeredStyles: boolean, styleProperty?: string};
+export type ExtraPropTransformsConfig = {[key: string]: ExtraPropTransformConfig};
+export type PerBlockExtraPropTransforms = {transforms: [[string, ...string[]], ExtraPropTransformConfig][], appliesInEditor: boolean};
+
+export type HydratedSimpleNativeTabItem = Omit<HydratedSimpleNativePanel, 'group'>;
+export type HydratedSimpleNativeTab = Omit<SimpleNativeTab, 'items'>&{items: HydratedSimpleNativeTabItem[]};
+export type HydratedSimpleNativeTabGroup = {[tabTitle: string]: HydratedSimpleNativeTab};
+export type HydratedSimpleNativePanel = Omit<SimpleNativePanel, 'properties'>&{properties: HydratedLaidOutProperties};
+
+export type HydratedLaidOutProperties = (HydratedSimpleNativeProperty|HydratedSimpleNativeProperty[])[];
+
+export type HydratedInspectorPanelGroupedTabs = {[key in InspectorPanelGroup]?: [string, HydratedSimpleNativeTabGroup]};
+export type PreppedSimpleNativePanelsAndTabs = {panels: [string, HydratedSimpleNativePanel][], tabs: HydratedInspectorPanelGroupedTabs};
+
+export function isRootLevelPanelGroup(panelGroup: string|undefined) {
+	return panelGroup === undefined || panelGroup === "default" || panelGroup === "advanced" || panelGroup === "settings" || panelGroup === "styles";
+}
+
+export function buildDefaultValueFromDefinition(definition: HydratedSimpleNativeProperty|undefined, requireNonNullValueOnObject = true): any {
+	if (definition === undefined) {
+		return undefined;
+	} else if (definition.default !== undefined) {
+		return structuredClone(definition.default);
+	}
+	const typedChildren = Array.isArray(definition.children) ? definition.children : undefined;
+	if (!typedChildren?.length) {
+		return structuredClone(definition.default);
+	} else if (definition.type === 'array') {
+		return [];
+	} else if (definition.type !== 'object') {
+		return undefined;
+	}
+
+	const res = Object.fromEntries(typedChildren.map(def => [def.name, buildDefaultValueFromDefinition(def)]));
+	if (requireNonNullValueOnObject) {
+		for (const value of Object.values(res)) {
+			if (value !== undefined) {
+				return res;
+			}
+		}
+		return undefined;
+	}
+	return res;
+}

package/src/blocks/snp-api.ts

@@ -0,0 +1,5 @@
+export type {ActualBEPAttrs, ActualBlockEditProps, ActualBlockListBlockProps, ActualBlockSaveProps, BlockJsonNativePropsConfig, RegisterBlockAttrs, NonEmptyArray} from "../lib/useful-types";
+export {isBlockJsonNativePropsConfig, arrayIsNotEmpty} from "../lib/useful-types";
+export type {CSNPConfig} from "./csnp-api";
+export type * from "./common-native-property-constructors";
+export type * from "./simple-native-property-api";

package/src/blocks/snp-data-store.ts

@@ -0,0 +1,66 @@
+import type {ActualBlockEditProps} from "../lib/useful-types";
+import type {DataStore, HydratedSimpleNativeProperty} from "./simple-native-property-api";
+import {buildDefaultValueFromDefinition} from "./simple-native-property-internal-shared";
+
+export abstract class SNPDataStore implements DataStore<ActualBlockEditProps> {
+	private readonly managedPropertyNames: {[propertyName in string]: true};
+
+	public constructor(
+		protected explicitBlockEditProps: ActualBlockEditProps,
+		private attributeCache: Record<string, any>
+	) {
+		this.managedPropertyNames = Object.create(null);
+	}
+
+	get blockEditProps() {
+		return this.explicitBlockEditProps;
+	}
+
+	getValue(attr: string): any {
+		if (attr in this.attributeCache) {
+			return this.attributeCache[attr];
+		}
+		const existingValue = this.getAttribute(attr);
+		return this.attributeCache[attr] = existingValue;
+	}
+	setValue(attr: string, value: any) {
+		this.attributeCache[attr] = value;
+		return this.setAttribute(attr, value);
+	}
+	handlesProperty(name: string): boolean {
+		return name in this.managedPropertyNames;
+	}
+
+	reattach(explicitBlockEditProps: ActualBlockEditProps, attributeCache: Record<string, any>) {
+		if (this.explicitBlockEditProps !== explicitBlockEditProps) { // If the block's properties haven't changed, there's no reason to clear the attribute cache
+			this.explicitBlockEditProps = explicitBlockEditProps;
+			this.attributeCache = attributeCache;
+		}
+		return this;
+	}
+
+	protected abstract getAttribute(name: string): any;
+	protected abstract setAttribute(name: string, value: any): void;
+
+	protected getCachedValue(attr: string) {
+		return this.attributeCache[attr];
+	}
+	protected hasCachedValue(attr: string) {
+		return attr in this.attributeCache;
+	}
+
+	addProperty(property: HydratedSimpleNativeProperty, writeThroughOnUndefined = true) {
+		if (this.managedPropertyNames[property.name]) {
+			return;
+		}
+		if (this.getAttribute(property.name) === undefined) {
+			if (writeThroughOnUndefined) {
+				this.setValue(property.name, buildDefaultValueFromDefinition(property));
+			} else {
+				this.attributeCache[property.name] = buildDefaultValueFromDefinition(property);
+			}
+		}
+
+		this.managedPropertyNames[property.name] = true;
+	}
+}

package/src/blocks/utilities.ts

@@ -0,0 +1,80 @@
+import {type BlockStyle, type BlockVariation, registerBlockStyle, registerBlockVariation, unregisterBlockStyle, unregisterBlockVariation} from "@wordpress/blocks";
+import {store as realBlockEditorStore} from "@wordpress/block-editor";
+import type * as BlockEditorActions from "@wordpress/block-editor/store/actions";
+import type * as BlockEditorSelectors from "@wordpress/block-editor/store/selectors";
+import type {ReduxStoreConfig, StoreDescriptor} from "@wordpress/data/types";
+import domReady from "@wordpress/dom-ready";
+
+import type {PairNormalizedPickableOptions} from "../controls";
+
+export function registerBlockStyles(blockName: string|string[], ...blockStyles: BlockStyle[]) {
+	domReady(() => {
+		forStringOrStrings(blockName, bn => {
+			for (const blockStyle of blockStyles) {
+				registerBlockStyle(bn, blockStyle);
+			}
+		});
+		if (Array.isArray(blockName)) {
+			for (const bn of blockName) {
+				for (const blockStyle of blockStyles) {
+					registerBlockStyle(bn, blockStyle);
+				}
+			}
+		} else {
+			for (const blockStyle of blockStyles) {
+				registerBlockStyle(blockName, blockStyle);
+			}
+		}
+	});
+}
+export function unregisterBlockStyles(blockName: string|string[], ...blockStyleNames: string[]) {
+	domReady(() => {
+		forStringOrStrings(blockName, bn => {
+			for (const blockStyleName of blockStyleNames) {
+				unregisterBlockStyle(bn, blockStyleName);
+			}
+		});
+	});
+}
+
+export function registerBlockVariations(blockName: string, ...blockVariations: BlockVariation[]) {
+	domReady(() => {
+		forStringOrStrings(blockName, bn => registerBlockVariation(bn, blockVariations));
+	});
+}
+export function unregisterBlockVariations(blockName: string, ...blockVariationNames: string[]) {
+	domReady(() => {
+		forStringOrStrings(blockName, bn => unregisterBlockVariation(bn, blockVariationNames));
+	});
+}
+
+export function convertToSelectControlOptions(response: unknown): PairNormalizedPickableOptions<string> {
+	if (response === null || response === undefined) {
+		return [];
+	} else if (typeof response === 'object') {
+		return (Array.isArray(response) ? response : Object.entries(response)).toSorted(([a], [b]) => a.localeCompare(b));
+	} else {
+		console.warn("An invalid response type was passed to convertToSelectControlOptions:", response);
+		return [[String(response), String(response)]];
+	}
+}
+
+type AddArgument<FirstArg, Fn extends (...args: any[]) => any> =
+	Fn extends (...arg: [...infer PrevArg]) => infer Return
+		? (...args: [FirstArg, ...PrevArg]) => Return
+		: never;
+type SelectorInflater<T extends {[name: string]: (...args: any[]) => any}> = {[name in keyof T]: AddArgument<any, T[name]>};
+export interface BlockEditorStoreDescriptor extends StoreDescriptor<ReduxStoreConfig<any, typeof BlockEditorActions, SelectorInflater<typeof BlockEditorSelectors>>> {
+	name: "core/block-editor";
+}
+export const blockEditorStore = realBlockEditorStore as BlockEditorStoreDescriptor;
+
+export function forStringOrStrings(stringOrStrings: string|string[], action: (string: string) => void) {
+	if (Array.isArray(stringOrStrings)) {
+		for (const string of stringOrStrings) {
+			action(string);
+		}
+	} else {
+		action(stringOrStrings);
+	}
+}

package/src/controls/AsynchronousFormTokenField.tsx

@@ -0,0 +1,85 @@
+import {Spinner, FormTokenField} from '@wordpress/components';
+import {useCallback} from "@wordpress/element";
+import {__} from "@wordpress/i18n";
+
+import type {SNPControlSlots} from "../blocks";
+import {useMultiSingleConversionLayer} from "./hooks/useMultiSingleConversionLayer";
+import {useSuggestions} from "./hooks/useSuggestions";
+import {useTokenManager} from "./hooks/useTokenManager";
+import type {TokenItem} from "../lib/useful-types";
+
+// The strange values correspond to the literals that are expected by TokenItem.status, which allows the assignment code to be cleaner
+export const enum ValidationState {
+	Valid = 'success',
+	Invalid = 'error',
+	Validating = 'validating',
+	Waiting = 'waiting'
+}
+
+type AsynchronousFormTokenFieldPropsBase = {
+	label?: string;
+	help?: string;
+
+	validationQuery(tokens: string[]): Promise<Array<TokenItem>>;
+	suggestionQuery(input: string): Promise<Array<string>>;
+	makeTokenFromSuggestion(suggestion: string): TokenItem;
+	validator?: (value: string) => boolean;
+	expandOnFocus?: boolean;
+}&Partial<Pick<SNPControlSlots, 'Messages'>>;
+type AsynchronousFormTokenFieldPropsSingle = AsynchronousFormTokenFieldPropsBase&{
+	value?: string;
+	onChange: (value: string) => void;
+	multiple: false;
+};
+type AsynchronousFormTokenFieldPropsMultiple = AsynchronousFormTokenFieldPropsBase&{
+	value?: string[];
+	onChange: (value: string[]) => void;
+	multiple?: true|undefined;
+};
+export type AsynchronousFormTokenFieldProps = AsynchronousFormTokenFieldPropsSingle|AsynchronousFormTokenFieldPropsMultiple;
+
+/**
+ * @deprecated use ExtendedFormTokenField instead
+ */
+export function AsynchronousFormTokenField(props: AsynchronousFormTokenFieldProps) {
+	const {help, expandOnFocus = false} = props;
+
+	const [value, setValue] = useMultiSingleConversionLayer(props.value, props.onChange, props.makeTokenFromSuggestion, props.multiple);
+
+	const {
+		currentTokens, dispatchValueUpdate, hasValidationError, isInitializing, isValidating, tokenTitleMappings
+	} = useTokenManager(value, setValue, props.validationQuery, props.makeTokenFromSuggestion);
+	const {
+		hasLoadingError, isLoading, suggestions, input, setInput
+	} = useSuggestions(undefined, {expandOnFocus, getSuggestions: props.suggestionQuery});
+
+	const displayTransform = useCallback((token: string) => tokenTitleMappings[token] ?? token, [tokenTitleMappings]);
+	const onFocus = useCallback(() => setInput(input), [input]);
+
+	if (isInitializing) {
+		return <Spinner />;
+	}
+
+	//TODO: If focus is in field but user hasn't started typing, show a message telling them to start typing
+	return <>
+		<FormTokenField
+			value={currentTokens}
+			label={props.label}
+			placeholder="Start typing to see suggestions"
+			suggestions={suggestions}
+			onChange={dispatchValueUpdate}
+			maxLength={props.multiple === false ? 1 : undefined}
+			__experimentalValidateInput={props.validator}
+			__experimentalAutoSelectFirstMatch={true}
+			__experimentalExpandOnFocus={expandOnFocus}
+			displayTransform={displayTransform}
+			onInputChange={setInput}
+			onFocus={onFocus}
+		/>
+		{help && <div><span className="components-form-token-field__help">{help}</span></div>}
+		{hasLoadingError && <div><Spinner /><span className="components-form-token-field__help">{__("An Error Occurred While Loading Suggestions")}</span></div>}
+		{isLoading && <div><Spinner /><span className="components-form-token-field__help">{__("Updating Suggestions")}</span></div>}
+		{hasValidationError && <div><Spinner /><span className="components-form-token-field__help">{__("An Error Occurred While Validating")}</span></div>}
+		{isValidating && <div><Spinner /><span className="components-form-token-field__help">{__("Validating")}</span></div>}
+	</>;
+}