@wordpress/core-data 7.38.1-next.v.0 → 7.39.0

package/src/utils/crdt-selection.ts

@@ -0,0 +1,205 @@
+/**
+ * WordPress dependencies
+ */
+import { dispatch, select } from '@wordpress/data';
+// @ts-expect-error No exported types.
+import { store as blockEditorStore } from '@wordpress/block-editor';
+// @ts-expect-error No exported types.
+import { isUnmodifiedBlock } from '@wordpress/blocks';
+import { type CRDTDoc, Y } from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import {
+	createBlockSelectionHistory,
+	YSelectionType,
+	type BlockSelectionHistory,
+	type YFullSelection,
+	type YSelection,
+} from './block-selection-history';
+import { findBlockByClientIdInDoc } from './crdt-utils';
+import type { WPBlockSelection, WPSelection } from '../types';
+
+// WeakMap to store BlockSelectionHistory instances per Y.Doc
+const selectionHistoryMap = new WeakMap< CRDTDoc, BlockSelectionHistory >();
+
+/**
+ * Get or create a BlockSelectionHistory instance for a given Y.Doc.
+ *
+ * @param ydoc The Y.Doc to get the selection history for
+ * @return The BlockSelectionHistory instance
+ */
+function getBlockSelectionHistory( ydoc: CRDTDoc ): BlockSelectionHistory {
+	let history = selectionHistoryMap.get( ydoc );
+
+	if ( ! history ) {
+		history = createBlockSelectionHistory( ydoc );
+		selectionHistoryMap.set( ydoc, history );
+	}
+
+	return history;
+}
+
+export function getSelectionHistory( ydoc: CRDTDoc ): YFullSelection[] {
+	return getBlockSelectionHistory( ydoc ).getSelectionHistory();
+}
+
+export function updateSelectionHistory(
+	ydoc: CRDTDoc,
+	wpSelection: WPSelection
+): void {
+	return getBlockSelectionHistory( ydoc ).updateSelection( wpSelection );
+}
+
+/**
+ * Convert a YSelection to a WPBlockSelection.
+ * @param ySelection The YSelection (relative) to convert
+ * @param ydoc       The Y.Doc to convert the selection to a block selection for
+ * @return The converted WPBlockSelection, or null if the conversion fails
+ */
+function convertYSelectionToBlockSelection(
+	ySelection: YSelection,
+	ydoc: Y.Doc
+): WPBlockSelection | null {
+	if ( ySelection.type === YSelectionType.RelativeSelection ) {
+		const { relativePosition, attributeKey, clientId } = ySelection;
+
+		const absolutePosition = Y.createAbsolutePositionFromRelativePosition(
+			relativePosition,
+			ydoc
+		);
+
+		if ( absolutePosition ) {
+			return {
+				clientId,
+				attributeKey,
+				offset: absolutePosition.index,
+			};
+		}
+	} else if ( ySelection.type === YSelectionType.BlockSelection ) {
+		return {
+			clientId: ySelection.clientId,
+			attributeKey: undefined,
+			offset: undefined,
+		};
+	}
+
+	return null;
+}
+
+/**
+ * Given a Y.Doc and a selection history, find the most recent selection
+ * that exists in the document. Skip any selections that are not in the document.
+ * @param ydoc             The Y.Doc to find the selection in
+ * @param selectionHistory The selection history to check
+ * @return The most recent selection that exists in the document, or null if no selection exists.
+ */
+function findSelectionFromHistory(
+	ydoc: Y.Doc,
+	selectionHistory: YFullSelection[]
+): WPSelection | null {
+	// Try each position until we find one that exists in the document
+	for ( const positionToTry of selectionHistory ) {
+		const { start, end } = positionToTry;
+		const startBlock = findBlockByClientIdInDoc( start.clientId, ydoc );
+		const endBlock = findBlockByClientIdInDoc( end.clientId, ydoc );
+
+		if ( ! startBlock || ! endBlock ) {
+			// This block no longer exists, skip it.
+			continue;
+		}
+
+		const startBlockSelection = convertYSelectionToBlockSelection(
+			start,
+			ydoc
+		);
+		const endBlockSelection = convertYSelectionToBlockSelection(
+			end,
+			ydoc
+		);
+
+		if ( startBlockSelection === null || endBlockSelection === null ) {
+			continue;
+		}
+
+		return {
+			selectionStart: startBlockSelection,
+			selectionEnd: endBlockSelection,
+		};
+	}
+
+	return null;
+}
+
+/**
+ * Restore the selection to the most recent selection in history that is
+ * available in the document.
+ * @param selectionHistory The selection history to restore
+ * @param ydoc             The Y.Doc where blocks are stored
+ */
+export function restoreSelection(
+	selectionHistory: YFullSelection[],
+	ydoc: Y.Doc
+): void {
+	// Find the most recent selection in history that is available in
+	// the document.
+	const selectionToRestore = findSelectionFromHistory(
+		ydoc,
+		selectionHistory
+	);
+
+	if ( selectionToRestore === null ) {
+		// Case 1: No blocks in history are available for restoration.
+		// Do nothing.
+		return;
+	}
+
+	const { getBlock } = select( blockEditorStore );
+	const { resetSelection } = dispatch( blockEditorStore );
+	const { selectionStart, selectionEnd } = selectionToRestore;
+	const isSelectionInSameBlock =
+		selectionStart.clientId === selectionEnd.clientId;
+
+	if ( isSelectionInSameBlock ) {
+		// Case 2: After content is restored, the selection is available
+		// within the same block
+
+		const block = getBlock( selectionStart.clientId );
+		const isBlockEmpty = block && isUnmodifiedBlock( block );
+		const isBeginningOfEmptyBlock =
+			0 === selectionStart.offset &&
+			0 === selectionEnd.offset &&
+			isBlockEmpty;
+
+		if ( isBeginningOfEmptyBlock ) {
+			// Case 2a: When the content in a block has been removed after an
+			// undo, WordPress will set the selection to the block's client ID
+			// with an undefined startOffset and endOffset.
+			//
+			// To match the default behavior and tests, exclude the selection
+			// offset when resetting to position 0.
+			const selectionStartWithoutOffset = {
+				clientId: selectionStart.clientId,
+			};
+			const selectionEndWithoutOffset = {
+				clientId: selectionEnd.clientId,
+			};
+
+			resetSelection(
+				selectionStartWithoutOffset,
+				selectionEndWithoutOffset,
+				0
+			);
+		} else {
+			// Case 2b: Otherwise, reset including the saved selection offset.
+			resetSelection( selectionStart, selectionEnd, 0 );
+		}
+	} else {
+		// Case 3: A multi-block selection was made. resetSelection() can only
+		// restore selections within the same block.
+		// When a multi-block selection is made, selectionEnd represents
+		// where the user's cursor ended.
+		resetSelection( selectionEnd, selectionEnd, 0 );
+	}
+}

package/src/utils/crdt-user-selections.ts

@@ -189,12 +189,16 @@ function getCursorPosition(
 	blocks: YBlocks
 ): CursorPosition | null {
 	const block = findBlockByClientId( selection.clientId, blocks );
-	if ( ! block ) {
+	if (
+		! block ||
+		! selection.attributeKey ||
+		undefined === selection.offset
+	) {
 		return null;
 	}
 
-	const attributes = block.get( 'attributes' ) as Y.Map< Y.Text >;
-	const currentYText = attributes.get( selection.attributeKey ) as Y.Text;
+	const attributes = block.get( 'attributes' );
+	const currentYText = attributes?.get( selection.attributeKey ) as Y.Text;
 
 	const relativePosition = Y.createRelativePositionFromTypeIndex(
 		currentYText,

package/src/utils/crdt-utils.ts

@@ -3,6 +3,13 @@
  */
 import { Y } from '@wordpress/sync';
 
+/**
+ * Internal dependencies
+ */
+import type { YBlock, YBlocks } from './crdt-blocks';
+import type { YPostRecord } from './crdt';
+import { CRDT_RECORD_MAP_KEY } from '../sync';
+
 /**
  * A YMapRecord represents the shape of the data stored in a Y.Map.
  */
@@ -75,3 +82,50 @@ export function isYMap< T extends YMapRecord >(
 ): value is YMapWrap< T > {
 	return value instanceof Y.Map;
 }
+
+/**
+ * Given a block ID and a Y.Doc, find the block in the document.
+ *
+ * @param blockId The block ID to find
+ * @param ydoc    The Y.Doc to find the block in
+ * @return The block, or null if the block is not found
+ */
+export function findBlockByClientIdInDoc(
+	blockId: string,
+	ydoc: Y.Doc
+): YBlock | null {
+	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
+	const blocks = ymap.get( 'blocks' );
+
+	if ( ! ( blocks instanceof Y.Array ) ) {
+		return null;
+	}
+
+	return findBlockByClientIdInBlocks( blockId, blocks );
+}
+
+function findBlockByClientIdInBlocks(
+	blockId: string,
+	blocks: YBlocks
+): YBlock | null {
+	for ( const block of blocks ) {
+		if ( block.get( 'clientId' ) === blockId ) {
+			return block;
+		}
+
+		const innerBlocks = block.get( 'innerBlocks' );
+
+		if ( innerBlocks && innerBlocks.length > 0 ) {
+			const innerBlock = findBlockByClientIdInBlocks(
+				blockId,
+				innerBlocks
+			);
+
+			if ( innerBlock ) {
+				return innerBlock;
+			}
+		}
+	}
+
+	return null;
+}

package/src/utils/crdt.ts

@@ -8,11 +8,18 @@ import fastDeepEqual from 'fast-deep-equal/es6/index.js';
  */
 // @ts-expect-error No exported types.
 import { __unstableSerializeAndClean } from '@wordpress/blocks';
-import { type CRDTDoc, type ObjectData, Y } from '@wordpress/sync';
+import {
+	type CRDTDoc,
+	type ObjectData,
+	type SyncConfig,
+	Y,
+} from '@wordpress/sync';
 
 /**
  * Internal dependencies
  */
+import { BaseAwareness } from '../awareness/base-awareness';
+import { type BaseState } from '../awareness/types';
 import {
 	mergeCrdtBlocks,
 	type Block,
@@ -27,6 +34,7 @@ import {
 	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 } from '../sync';
 import type { WPSelection } from '../types';
+import { updateSelectionHistory } from './crdt-selection';
 import {
 	createYMap,
 	getRootMap,
@@ -47,6 +55,7 @@ export type PostChanges = Partial< Post > & {
 export interface YPostRecord extends YMapRecord {
 	author: number;
 	blocks: YBlocks;
+	categories: number[];
 	comment_status: string;
 	date: string | null;
 	excerpt: string;
@@ -66,6 +75,7 @@ export interface YPostRecord extends YMapRecord {
 const allowedPostProperties = new Set< string >( [
 	'author',
 	'blocks',
+	'categories',
 	'comment_status',
 	'date',
 	'excerpt',
@@ -94,7 +104,7 @@ const disallowedPostMetaKeys = new Set< string >( [
  * @param {Partial< ObjectData >} changes
  * @return {void}
  */
-export function defaultApplyChangesToCRDTDoc(
+function defaultApplyChangesToCRDTDoc(
 	ydoc: CRDTDoc,
 	changes: ObjectData
 ): void {
@@ -240,9 +250,22 @@ export function applyPostChangesToCRDTDoc(
 			}
 		}
 	} );
+
+	// Process changes that we don't want to persist to the CRDT document.
+	if ( changes.selection ) {
+		const selection = changes.selection;
+		// Persist selection changes at the end of the current event loop.
+		// This allows undo meta to be saved with the current selection before
+		// it is overwritten by the new selection from Gutenberg.
+		// Without this, selection history will already contain the latest
+		// selection (after this change) when the undo stack is saved.
+		setTimeout( () => {
+			updateSelectionHistory( ydoc, selection );
+		}, 0 );
+	}
 }
 
-export function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
+function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
 	return getRootMap( crdtDoc, CRDT_RECORD_MAP_KEY ).toJSON();
 }
 
@@ -382,6 +405,16 @@ export function getPostChangesFromCRDTDoc(
 	return changes;
 }
 
+/**
+ * This default sync config can be used for entities that are flat maps of
+ * primitive values and do not require custom logic to merge changes.
+ */
+export const defaultSyncConfig: SyncConfig< BaseState > = {
+	applyChangesToCRDTDoc: defaultApplyChangesToCRDTDoc,
+	createAwareness: ( ydoc: CRDTDoc ) => new BaseAwareness( ydoc ),
+	getChangesFromCRDTDoc: defaultGetChangesFromCRDTDoc,
+};
+
 /**
  * Extract the raw string value from a property that may be a string or an object
  * with a `raw` property (`RenderedText`).