@plaudit/gutenberg-api-extensions 2.82.0 → 2.84.0

package/src/blocks/data-controller/utils.ts

@@ -0,0 +1,339 @@
+import {doAction} from "@wordpress/hooks";
+
+import {Draft, produce} from "immer";
+
+import type {DCNode, DCStoreState} from "../data-controller";
+import {MoveError} from "../MoveError";
+import {PathError, PathErrorType} from "../PathError";
+import {buildDefaultValueFromDefinition} from "../simple-native-property-internal-shared";
+import type {DataStore, HydratedSimpleNativeProperty, NodePath, RawPath} from "../simple-native-property-api";
+
+export function removeFromParentNode(parentNode: any|undefined, path: RawPath) {
+	if (typeof parentNode !== 'object' || parentNode === undefined || parentNode === null) {
+		throw new PathError("Encountered a non-existent node while expecting one.", path);
+	}
+	const nodeName = path[path.length - 1];
+	if (typeof nodeName === 'string') {
+		if (Array.isArray(parentNode)) {
+			throw new PathError(
+				"Encountered a node with indexed descendants while expecting one with string-keyed descendants.",
+				path, path.length - 1);
+		}
+		delete parentNode[nodeName];
+	} else if (nodeName === undefined) {
+		throw new PathError("Encountered an undefined name in a path.", path);
+	} else {
+		if (!Array.isArray(parentNode)) {
+			throw new PathError(
+				"Encountered a node with string-keyed descendants while expecting one with indexed descendants.",
+				path, path.length - 1);
+		}
+		parentNode.splice(nodeName, 1);
+	}
+}
+
+export function moveNodeWithinParent(parentNode: any|undefined|null, path: RawPath, move: {from: number, to: number}|{from: string, to: string}) {
+	if (typeof parentNode !== 'object' || parentNode === undefined || parentNode === null) {
+		throw new PathError("Encountered a non-existent node while expecting one.", path);
+	}
+	if (isNumericMove(move)) {
+		if (!Array.isArray(parentNode)) {
+			throw new MoveError("Attempted to move a child of a node with string-keyed descendants by index", path, move);
+		}
+		if (move.from > move.to) {
+			parentNode.splice(move.to, 0, ...parentNode.splice(move.from, 1));
+		} else { //We know that
+			parentNode.splice(move.to - 1, 0, ...parentNode.splice(move.from, 1));
+		}
+	} else {
+		if (Array.isArray(parentNode)) {
+			throw new MoveError("Attempted to move a child of a node with indexed descendants by string-key", path, move);
+		}
+		if (parentNode[move.to] !== undefined) {
+			throw new MoveError("Attempted to move a string-keyed child to the same key as another", path, move);
+		}
+	}
+}
+export function isNumericMove(move: {from: number, to: number}|{from: string, to: string}): move is {from: number, to: number} {
+	return typeof move.from === 'number' && typeof move.to === 'number';
+}
+
+export function resolveParentNodeDefinition(root: DCNode, path: RawPath): HydratedSimpleNativeProperty|undefined {
+	if (path.length < 2) {
+		throw new PathError("Unable to get the parent node of a path with less than two nodes", path, path.length - 1, PathErrorType.INSUFFICIENT_LENGTH);
+	}
+	return walkToNode(root, path.slice(0, path.length - (typeof path[path.length - 2] === 'number' ? 2 : 1))).definition;
+}
+
+export function populateValueBasedOnDefinition(value: any, definition: HydratedSimpleNativeProperty|undefined): any {
+	const typedChildren = Array.isArray(definition?.children) ? definition.children : definition?.children?.[value?.type];
+	if (!typedChildren?.length) {
+		return value ?? buildDefaultValueFromDefinition(definition);
+	} else if (value === null || value === undefined) {
+		return buildDefaultValueFromDefinition(definition);
+	} else if (typeof value !== 'object') {
+		return value;
+	} else if (Array.isArray(value)) {
+		return value;
+	}
+	return {...value, ...Object.fromEntries(typedChildren.map(def => [def.name, populateValueBasedOnDefinition(value[def.name], def)]))};
+}
+
+export function walkToNode(root: DCNode, path: RawPath): DCNode {
+	let current = root;
+	for (let i = 0; i < path.length; i++) {
+		current = descendIntoDCNodeChild(current, path, i);
+	}
+	return current;
+}
+export function descendIntoDCNodeChild(current: DCNode|undefined, path: RawPath, i: number): DCNode {
+	if (current?.children === undefined) {
+		throw new PathError("Encountered a leaf node while expecting one with descendants.", path, i, PathErrorType.UNEXPECTED_LEAF);
+	}
+	const pathNode = path[i];
+	if (typeof pathNode === 'string') {
+		if (Array.isArray(current.children)) {
+			throw new PathError("Encountered a node with indexed descendants while expecting one with string-keyed descendants.", path, i);
+		}
+		current = current.children[pathNode];
+	} else if (pathNode === undefined) {
+		throw new PathError("Encountered an undefined name in a path.", path, i);
+	} else {
+		if (!Array.isArray(current.children)) {
+			throw new PathError("Encountered a node with string-keyed descendants while expecting one with indexed descendants.", path, i);
+		}
+		current = current.children[pathNode];
+	}
+	if (current === undefined) {
+		throw new PathError("Encountered a non-existent node while expecting one.", path, i, PathErrorType.UNEXPECTED_LEAF);
+	}
+	return current;
+}
+
+export function getDataStore(property: string, state: Draft<DCStoreState>, throwOnError: false): DataStore|undefined;
+export function getDataStore(property: string, state: Draft<DCStoreState>, throwOnError?: undefined|true): DataStore;
+export function getDataStore(property: string, state: Draft<DCStoreState>, throwOnError = true): DataStore|undefined {
+	let dataStore = state.dataStores.byProperty[property];
+	if (dataStore) {
+		return dataStore;
+	}
+	dataStore = state.dataStores.list.find(dataStore => dataStore.handlesProperty(property));
+	if (dataStore) {
+		console.warn(`Unable to locate the DataStore for ${property} via the byProperty map, but did find a DataStore that handles that property. This should not be possible.`);
+	} else if (throwOnError) {
+		throw new Error(`Unable to resolve the dataStore for ${property} on block ${state.blockClientId}`);
+	}
+	return dataStore;
+}
+
+export function getOptionalValue(path: NodePath, state: Draft<DCStoreState>) {
+	try {
+		return walkToNodeInValue(getDataStore(path[0], state).getValue(path[0]), path);
+	} catch (e) {
+		if (e instanceof PathError) {
+			return undefined;
+		}
+		throw e;
+	}
+}
+
+export function removeValueFromBackingDataStore(dataStore: DataStore, path: NodePath) {
+	const dsValue = dataStore.getValue(path[0]);
+	if (path.length === 1) {
+		dataStore.setValue(path[0], undefined);
+	} else {
+		dataStore.setValue(path[0], produce(dsValue, (dsValueDraft: any) => {
+			const nodeParent = walkToNodeInValue(dsValueDraft, path.slice(0, path.length - 1));
+			const nodeName = path[path.length - 1];
+			if (typeof nodeName === 'string') {
+				delete nodeParent[nodeName];
+			} else if (nodeName === undefined) {
+				throw new PathError("Encountered an undefined name in a path.", path);
+			} else {
+				(nodeParent as any[]).splice(nodeName, 1);
+			}
+		}));
+	}
+}
+export function writeValueToBackingDataStoreWithCorrections(path: NodePath, state: DCStoreState, value: any) {
+	if (typeof value === 'number' && Number.isNaN(value)) {
+		value = undefined; // This ensures that NaN's don't get stored
+	}
+	const rootDCNode = state.treeRoot.children[path[0]];
+	if (rootDCNode === undefined) {
+		throw new PathError("Encountered a path pointing to a non-existent root node.", path, 0);
+	}
+	const dataStore = getDataStore(path[0], state);
+
+	// This path both handles scalar values and ensures that the root "value" of Groups and Lists are initialized before writing the actual attribute
+	// In order to avoid accidentally overwriting group data when lazily adding items (i.e. via a ToolsPanel instance), we skip this code path if the group's root value has already been initialized
+	if (path.length === 1 || (value === undefined && dataStore.getValue(path[0]) === undefined)) {
+		const writtenValue = value ?? buildDefaultValueFromDefinition(rootDCNode.definition, path.length === 1);
+		dataStore.setValue(path[0], writtenValue);
+		if (rootDCNode.definition) {
+			doAction('plaudit.gutenbergApiExtensions.simpleNativeProperties.afterWrite', writtenValue, rootDCNode.definition, dataStore);
+		}
+		if (path.length === 1) {
+			return;
+		}
+	}
+
+	let closestUsableDefinition = rootDCNode.definition;
+	let lastWrittenValue: unknown;
+	dataStore.setValue(path[0], produce(dataStore.getValue(path[0]), (dsValueDraft: any) => {
+		let currentDSValue = dsValueDraft;
+		let currentDCNode = rootDCNode;
+		for (let i = 1; i < path.length - 1; i++) {
+			const nodeName = path[i];
+			currentDCNode = descendIntoDCNodeChild(currentDCNode, path, i);
+			if (typeof nodeName === 'string') {
+				//We only update the definition being used when we descend into a new node proper
+				closestUsableDefinition = currentDCNode.definition;
+			} else if (nodeName === undefined) {
+				throw new PathError("Encountered an undefined name in a path.", path, i);
+			}
+
+			let nextDSValue = descendIntoDSValueNodeChild(currentDSValue, path, i);
+			if (nextDSValue === undefined) {
+				lastWrittenValue = currentDSValue[nodeName] = buildDefaultValueFromDefinition(closestUsableDefinition);
+				currentDSValue = descendIntoDSValueNodeChild(currentDSValue, path, i);
+				if (currentDSValue === undefined) {
+					throw new PathError("Encountered a leaf node while expecting one with descendants.", path, i, PathErrorType.UNEXPECTED_LEAF);
+				}
+			} else {
+				currentDSValue = nextDSValue;
+			}
+		}
+		const nodeName = path[path.length - 1];
+		if (nodeName === undefined) {
+			throw new PathError("Encountered an undefined name in a path.", path);
+		}
+		lastWrittenValue = currentDSValue[nodeName] = value;
+	}));
+	if (closestUsableDefinition) {
+		doAction('plaudit.gutenbergApiExtensions.simpleNativeProperties.afterWrite', lastWrittenValue, closestUsableDefinition, dataStore);
+	}
+}
+export function writeValueToBackingDataStore(dataStore: DataStore, path: NodePath, value: any) {
+	if (typeof value === 'number' && Number.isNaN(value)) {
+		value = undefined; // This ensures that NaN's don't get stored
+	}
+	const dsValue = dataStore.getValue(path[0]);
+	if (path.length === 1) {
+		dataStore.setValue(path[0], value);
+	} else {
+		dataStore.setValue(path[0], produce(dsValue, (dsValueDraft: any) => {
+			const nodeParent = walkToNodeInValue(dsValueDraft, path.slice(0, path.length - 1));
+			const nodeName = path[path.length - 1];
+			if (nodeName === undefined) {
+				throw new PathError("Encountered an undefined name in a path.", path);
+			}
+			nodeParent[nodeName] = value;
+		}));
+	}
+}
+
+/**
+ * @param dsValue a value from a {@link DataStore}
+ * @param path this is expected to be the entire path (including the node that was used to get {@link dsValue}
+ */
+export function walkToNodeInValue(dsValue: any, path: RawPath) {
+	let current = dsValue;
+	for (let i = 1; i < path.length; i++) {
+		if (current === undefined) {
+			throw new PathError("Encountered a leaf node while expecting one with descendants.", path, i, PathErrorType.UNEXPECTED_LEAF);
+		}
+		current = descendIntoDSValueNodeChild(current, path, i);
+	}
+	return current;
+}
+function descendIntoDSValueNodeChild(current: any, path: RawPath, i: number) {
+	const pathNode = path[i];
+	if (typeof pathNode === 'string') {
+		if (Array.isArray(current)) {
+			throw new PathError("Encountered a node with indexed descendants while expecting one with string-keyed descendants.", path, i);
+		}
+		current = current[pathNode];
+	} else if (pathNode === undefined) {
+		throw new PathError("Encountered an undefined name in a path.", path, i);
+	} else {
+		if (!Array.isArray(current)) {
+			throw new PathError("Encountered a node with string-keyed descendants while expecting one with indexed descendants.", path, i);
+		}
+		current = current[pathNode];
+	}
+	return current;
+}
+
+export enum TreeMutatorResult {
+	STOP, CONTINUE, SKIP_DESCENDANTS
+}
+export function applyToTree(tree: DCNode, mutator: (node: DCNode, path: NodePath) => TreeMutatorResult, path: RawPath = []) {
+	if (tree.children === undefined) {
+		return TreeMutatorResult.CONTINUE;
+	}
+
+	const steps: Array<[NodePath, DCNode]> = Array.isArray(tree.children)
+		? tree.children.map((node, index) => [path.toSpliced(path.length, 0, index) as NodePath, node])
+		: Object.entries(tree.children).map(([name, node]) => [path.toSpliced(path.length, 0, name) as NodePath, node]);
+
+	for (const [nodePath, node] of steps) {
+		const mutatorRes = mutator(node, nodePath);
+		if (!mutatorRes) {
+			return TreeMutatorResult.STOP;
+		} else if (mutatorRes === TreeMutatorResult.CONTINUE) {
+			if (!applyToTree(node, mutator, nodePath)) {
+				return TreeMutatorResult.STOP;
+			}
+		}
+	}
+	return TreeMutatorResult.CONTINUE;
+}
+
+export function buildNodeFromDataAndDefinition(data: any, definition: HydratedSimpleNativeProperty): DCNode {
+	const children = definition.children;
+	if (children) {
+		if (data === undefined || data === null) {
+			if (definition.type === 'array') {
+				return {rendered: true, condition: definition.condition, definition, validationError: "", children: []};
+			} else if (definition.type === 'object') {
+				if (Array.isArray(children)) {
+					return {
+						rendered: true, condition: definition.condition, definition, validationError: "",
+						children: Object.fromEntries(children.map(def => [def.name, buildNodeFromDataAndDefinition(undefined, def)]))
+					};
+				} else {
+					//TODO: We might need to throw an error here
+					return {rendered: true, condition: definition.condition, definition, validationError: "", children: {}};
+				}
+			}
+		} else if (typeof data === 'object') {
+			if (Array.isArray(data)) {
+				return {
+					rendered: true, condition: definition.condition, definition, validationError: "", children: data.map(item => {
+						const typedChildren = Array.isArray(children) ? children : children[item.type];
+						if (typedChildren === undefined) {
+							//TODO: We might need to throw an error here
+							return {children: [], rendered: true, validationError: ""};
+						}
+						return {
+							children: Object.fromEntries(typedChildren.map(def => [def.name, buildNodeFromDataAndDefinition(item[def.name], def)])),
+							rendered: true, validationError: ""
+						};
+					})
+				};
+			} else {
+				const typedChildren = Array.isArray(children) ? children : children[data.type];
+				if (typedChildren === undefined) {
+					//TODO: We might need to throw an error here
+					return {rendered: true, condition: definition.condition, definition, validationError: "", children: []};
+				}
+				return {
+					rendered: true, condition: definition.condition, definition, validationError: "",
+					children: Object.fromEntries(typedChildren.map(def => [def.name, buildNodeFromDataAndDefinition(data[def.name], def)]))
+				};
+			}
+		}
+	}
+	return {rendered: true, condition: definition.condition, definition, validationError: ""};
+}