@wordpress/core-data 7.38.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

@@ -0,0 +1,336 @@
+/**
+ * External dependencies
+ */
+import { Y, CRDT_RECORD_MAP_KEY } from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import type { YPostRecord } from './crdt';
+import type { YBlock, YBlocks } from './crdt-blocks';
+import { getRootMap } from './crdt-utils';
+import type { WPBlockSelection } from '../types';
+
+/**
+ * The type of selection.
+ */
+export enum SelectionType {
+	None = 'none',
+	Cursor = 'cursor',
+	SelectionInOneBlock = 'selection-in-one-block',
+	SelectionInMultipleBlocks = 'selection-in-multiple-blocks',
+	WholeBlock = 'whole-block',
+}
+
+/**
+ * The position of the cursor.
+ */
+export type CursorPosition = {
+	relativePosition: Y.RelativePosition;
+
+	// Also store the absolute offset index of the cursor from the perspective
+	// of the user who is updating the selection.
+	//
+	// Do not use this value directly, instead use `createAbsolutePositionFromRelativePosition()`
+	// on relativePosition for the most up-to-date positioning.
+	//
+	// This is used because local Y.Text changes (e.g. adding or deleting a character)
+	// can result in the same relative position if it is pinned to an unchanged
+	// character. With both of these values as editor state, a change in perceived
+	// position will always result in a redraw.
+	absoluteOffset: number;
+};
+
+export type SelectionNone = {
+	// The user has not made a selection.
+	type: SelectionType.None;
+};
+
+export type SelectionCursor = {
+	// The user has a cursor position in a block with no text highlighted.
+	type: SelectionType.Cursor;
+	blockId: string;
+	cursorPosition: CursorPosition;
+};
+
+export type SelectionInOneBlock = {
+	// The user has highlighted text in a single block.
+	type: SelectionType.SelectionInOneBlock;
+	blockId: string;
+	cursorStartPosition: CursorPosition;
+	cursorEndPosition: CursorPosition;
+};
+
+export type SelectionInMultipleBlocks = {
+	// The user has highlighted text over multiple blocks.
+	type: SelectionType.SelectionInMultipleBlocks;
+	blockStartId: string;
+	blockEndId: string;
+	cursorStartPosition: CursorPosition;
+	cursorEndPosition: CursorPosition;
+};
+
+export type SelectionWholeBlock = {
+	// The user has a non-text block selected, like an image block.
+	type: SelectionType.WholeBlock;
+	blockId: string;
+};
+
+export type SelectionState =
+	| SelectionNone
+	| SelectionCursor
+	| SelectionInOneBlock
+	| SelectionInMultipleBlocks
+	| SelectionWholeBlock;
+
+/**
+ * Converts WordPress block editor selection to a SelectionState.
+ *
+ * @param selectionStart - The start position of the selection
+ * @param selectionEnd   - The end position of the selection
+ * @param yDoc           - The Yjs document
+ * @return The SelectionState
+ */
+export function getSelectionState(
+	selectionStart: WPBlockSelection,
+	selectionEnd: WPBlockSelection,
+	yDoc: Y.Doc
+): SelectionState {
+	const ymap = getRootMap< YPostRecord >( yDoc, CRDT_RECORD_MAP_KEY );
+	const yBlocks = ymap.get( 'blocks' ) ?? new Y.Array< YBlock >();
+
+	const isSelectionEmpty = Object.keys( selectionStart ).length === 0;
+	const noSelection: SelectionNone = {
+		type: SelectionType.None,
+	};
+
+	if ( isSelectionEmpty ) {
+		// Case 1: No selection
+		return noSelection;
+	}
+
+	// When the page initially loads, selectionStart can contain an empty object `{}`.
+	const isSelectionInOneBlock =
+		selectionStart.clientId === selectionEnd.clientId;
+	const isCursorOnly =
+		isSelectionInOneBlock && selectionStart.offset === selectionEnd.offset;
+	const isSelectionAWholeBlock =
+		isSelectionInOneBlock &&
+		selectionStart.offset === undefined &&
+		selectionEnd.offset === undefined;
+
+	if ( isSelectionAWholeBlock ) {
+		// Case 2: A whole block is selected.
+		return {
+			type: SelectionType.WholeBlock,
+			blockId: selectionStart.clientId,
+		};
+	} else if ( isCursorOnly ) {
+		// Case 3: Cursor only, no text selected
+		const cursorPosition = getCursorPosition( selectionStart, yBlocks );
+
+		if ( ! cursorPosition ) {
+			// If we can't find the cursor position in block text, treat it as a non-selection.
+			return noSelection;
+		}
+
+		return {
+			type: SelectionType.Cursor,
+			blockId: selectionStart.clientId,
+			cursorPosition,
+		};
+	} else if ( isSelectionInOneBlock ) {
+		// Case 4: Selection in a single block
+		const cursorStartPosition = getCursorPosition(
+			selectionStart,
+			yBlocks
+		);
+		const cursorEndPosition = getCursorPosition( selectionEnd, yBlocks );
+
+		if ( ! cursorStartPosition || ! cursorEndPosition ) {
+			// If we can't find the cursor positions in block text, treat it as a non-selection.
+			return noSelection;
+		}
+
+		return {
+			type: SelectionType.SelectionInOneBlock,
+			blockId: selectionStart.clientId,
+			cursorStartPosition,
+			cursorEndPosition,
+		};
+	}
+
+	// Caes 5: Selection in multiple blocks
+	const cursorStartPosition = getCursorPosition( selectionStart, yBlocks );
+	const cursorEndPosition = getCursorPosition( selectionEnd, yBlocks );
+	if ( ! cursorStartPosition || ! cursorEndPosition ) {
+		// If we can't find the cursor positions in block text, treat it as a non-selection.
+		return noSelection;
+	}
+
+	return {
+		type: SelectionType.SelectionInMultipleBlocks,
+		blockStartId: selectionStart.clientId,
+		blockEndId: selectionEnd.clientId,
+		cursorStartPosition,
+		cursorEndPosition,
+	};
+}
+
+/**
+ * Get the cursor position from a selection.
+ *
+ * @param selection - The selection.
+ * @param blocks    - The blocks to search through.
+ * @return The cursor position, or null if not found.
+ */
+function getCursorPosition(
+	selection: WPBlockSelection,
+	blocks: YBlocks
+): CursorPosition | null {
+	const block = findBlockByClientId( selection.clientId, blocks );
+	if (
+		! block ||
+		! selection.attributeKey ||
+		undefined === selection.offset
+	) {
+		return null;
+	}
+
+	const attributes = block.get( 'attributes' );
+	const currentYText = attributes?.get( selection.attributeKey ) as Y.Text;
+
+	const relativePosition = Y.createRelativePositionFromTypeIndex(
+		currentYText,
+		selection.offset
+	);
+
+	return {
+		relativePosition,
+		absoluteOffset: selection.offset,
+	};
+}
+
+/**
+ * Find a block by its client ID.
+ *
+ * @param blockId - The client ID of the block.
+ * @param blocks  - The blocks to search through.
+ * @return The block if found, null otherwise.
+ */
+function findBlockByClientId(
+	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 = findBlockByClientId( blockId, innerBlocks );
+
+			if ( innerBlock ) {
+				return innerBlock;
+			}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Check if two selection states are equal.
+ *
+ * @param selection1 - The first selection state.
+ * @param selection2 - The second selection state.
+ * @return True if the selection states are equal, false otherwise.
+ */
+export function areSelectionsStatesEqual(
+	selection1: SelectionState,
+	selection2: SelectionState
+): boolean {
+	if ( selection1.type !== selection2.type ) {
+		return false;
+	}
+
+	switch ( selection1.type ) {
+		case SelectionType.None:
+			return true;
+
+		case SelectionType.Cursor:
+			return (
+				selection1.blockId ===
+					( selection2 as SelectionCursor ).blockId &&
+				areCursorPositionsEqual(
+					selection1.cursorPosition,
+					( selection2 as SelectionCursor ).cursorPosition
+				)
+			);
+
+		case SelectionType.SelectionInOneBlock:
+			return (
+				selection1.blockId ===
+					( selection2 as SelectionInOneBlock ).blockId &&
+				areCursorPositionsEqual(
+					selection1.cursorStartPosition,
+					( selection2 as SelectionInOneBlock ).cursorStartPosition
+				) &&
+				areCursorPositionsEqual(
+					selection1.cursorEndPosition,
+					( selection2 as SelectionInOneBlock ).cursorEndPosition
+				)
+			);
+
+		case SelectionType.SelectionInMultipleBlocks:
+			return (
+				selection1.blockStartId ===
+					( selection2 as SelectionInMultipleBlocks ).blockStartId &&
+				selection1.blockEndId ===
+					( selection2 as SelectionInMultipleBlocks ).blockEndId &&
+				areCursorPositionsEqual(
+					selection1.cursorStartPosition,
+					( selection2 as SelectionInMultipleBlocks )
+						.cursorStartPosition
+				) &&
+				areCursorPositionsEqual(
+					selection1.cursorEndPosition,
+					( selection2 as SelectionInMultipleBlocks )
+						.cursorEndPosition
+				)
+			);
+		case SelectionType.WholeBlock:
+			return (
+				selection1.blockId ===
+				( selection2 as SelectionWholeBlock ).blockId
+			);
+
+		default:
+			return false;
+	}
+}
+
+/**
+ * Check if two cursor positions are equal.
+ *
+ * @param cursorPosition1 - The first cursor position.
+ * @param cursorPosition2 - The second cursor position.
+ * @return True if the cursor positions are equal, false otherwise.
+ */
+function areCursorPositionsEqual(
+	cursorPosition1: CursorPosition,
+	cursorPosition2: CursorPosition
+): boolean {
+	const isRelativePositionEqual =
+		JSON.stringify( cursorPosition1.relativePosition ) ===
+		JSON.stringify( cursorPosition2.relativePosition );
+
+	// Ensure a change in calculated absolute offset results in a treating the cursor as modified.
+	// This is necessary because Y.Text relative positions can remain the same after text changes.
+	const isAbsoluteOffsetEqual =
+		cursorPosition1.absoluteOffset === cursorPosition2.absoluteOffset;
+
+	return isRelativePositionEqual && isAbsoluteOffsetEqual;
+}

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`).