SharedString DDS annotateAdjustRange

.changeset/ninety-dragons-fold.md

@@ -0,0 +1,30 @@
+---
+"fluid-framework": minor
+"@fluidframework/merge-tree": minor
+"@fluidframework/sequence": minor
+"@fluidframework/undo-redo": minor
+---
+---
+"section": feature
+---
+
+### SharedString DDS annotateAdjustRange
+
+This update introduces a new feature to the `SharedString` DDS, allowing for the adjustment of properties over a specified range. The `annotateAdjustRange` method enables users to apply adjustments to properties within a given range, providing more flexibility and control over property modifications.
+
+An adjustment is a modification applied to a property value within a specified range. Adjustments can be used to increment or decrement property values dynamically. They are particularly useful in scenarios where property values need to be updated based on user interactions or other events. For example, in a rich text editor, adjustments can be used for modifying indentation levels or font sizes, where multiple users could apply differing numerical adjustments.
+
+### Key Features and Use Cases:
+- **Adjustments with Constraints**: Adjustments can include optional minimum and maximum constraints to ensure the final value falls within specified bounds. This is particularly useful for maintaining consistent formatting in rich text editors.
+- **Consistent Property Changes**: The feature ensures that property changes are consistent, managing both local and remote changes effectively. This is essential for collaborative rich text editing where multiple users may be making adjustments simultaneously.
+- **Rich Text Formatting**: Adjustments can be used to modify text properties such as font size, indentation, or other formatting attributes dynamically based on user actions.
+
+### Configuration and Compatibility Requirements:
+This feature is only available when the configuration `Fluid.Sequence.mergeTreeEnableAnnotateAdjust` is set to `true`. Additionally, all collaborating clients must have this feature enabled to use it. If any client does not have this feature enabled, it will lead to the client exiting collaboration. A future major version of Fluid will enable this feature by default.
+
+### Usage Example:
+```typescript
+sharedString.annotateAdjustRange(start, end, {
+    key: { value: 5, min: 0, max: 10 }
+});
+```

packages/dds/merge-tree/api-report/merge-tree.legacy.alpha.api.md

@@ -216,7 +216,7 @@ export interface IMergeTreeDeltaCallbackArgs<TOperationType extends MergeTreeDel
 }
 
 // @alpha (undocumented)
-export type IMergeTreeDeltaOp = IMergeTreeInsertMsg | IMergeTreeRemoveMsg | IMergeTreeAnnotateMsg | IMergeTreeObliterateMsg | IMergeTreeObliterateSidedMsg;
+export type IMergeTreeDeltaOp = IMergeTreeInsertMsg | IMergeTreeRemoveMsg | IMergeTreeAnnotateMsg | IMergeTreeAnnotateAdjustMsg | IMergeTreeObliterateMsg | IMergeTreeObliterateSidedMsg;
 
 // @alpha (undocumented)
 export interface IMergeTreeDeltaOpArgs {
@@ -290,6 +290,7 @@ export type IMergeTreeOp = IMergeTreeDeltaOp | IMergeTreeGroupMsg;
 export interface IMergeTreeOptions {
     // (undocumented)
     catchUpBlobName?: string;
+    mergeTreeEnableAnnotateAdjust?: boolean;
     mergeTreeEnableObliterate?: boolean;
     mergeTreeEnableObliterateReconnect?: boolean;
     mergeTreeEnableSidedObliterate?: boolean;

packages/dds/merge-tree/package.json

@@ -250,6 +250,9 @@
 			"TypeAlias_Trackable": {
 				"backCompat": false
 			},
+			"Class_Client": {
+				"forwardCompat": false
+			},
 			"Class_PropertiesManager": {
 				"forwardCompat": false,
 				"backCompat": false

packages/dds/merge-tree/src/attributionPolicy.ts

@@ -152,7 +152,7 @@ function createPropertyTrackingMergeTreeCallbacks(
 				const shouldAttributeAnnotate =
 					op.type === MergeTreeDeltaType.ANNOTATE &&
 					// Only attribute annotations which change the tracked property
-					op.props[propName] !== undefined &&
+					(op.props?.[propName] !== undefined || op.adjust?.[propName] !== undefined) &&
 					(isLocal || (propertyDeltas !== undefined && propName in propertyDeltas));
 
 				if (shouldAttributeInsert || shouldAttributeAnnotate) {

packages/dds/merge-tree/src/client.ts

@@ -54,6 +54,7 @@ import {
 	toMoveInfo,
 } from "./mergeTreeNodes.js";
 import {
+	createAdjustRangeOp,
 	createAnnotateMarkerOp,
 	createAnnotateRangeOp,
 	// eslint-disable-next-line import/no-deprecated
@@ -77,9 +78,11 @@ import {
 	IRelativePosition,
 	MergeTreeDeltaType,
 	ReferenceType,
+	type AdjustParams,
+	type IMergeTreeAnnotateAdjustMsg,
 	type IMergeTreeObliterateSidedMsg,
 } from "./ops.js";
-import { PropertySet } from "./properties.js";
+import { PropertySet, type MapLike } from "./properties.js";
 import { DetachedReferencePosition, ReferencePosition } from "./referencePositions.js";
 import { Side, type InteriorSequencePlace } from "./sequencePlace.js";
 import { SnapshotLoader } from "./snapshotLoader.js";
@@ -245,6 +248,26 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		return annotateOp;
 	}
 
+	/**
+	 * adjusts a value
+	 */
+	public annotateAdjustRangeLocal(
+		start: number,
+		end: number,
+		adjust: MapLike<AdjustParams>,
+	): IMergeTreeAnnotateAdjustMsg | undefined {
+		const annotateOp = createAdjustRangeOp(start, end, adjust);
+
+		for (const [key, value] of Object.entries(adjust)) {
+			if (value.min !== undefined && value.max !== undefined && value.min > value.max) {
+				throw new UsageError(`min is greater than max for ${key}`);
+			}
+		}
+
+		this.applyAnnotateRangeOp({ op: annotateOp });
+		return annotateOp;
+	}
+
 	/**
 	 * Removes the range
 	 *
@@ -564,7 +587,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 		this._mergeTree.annotateRange(
 			range.start,
 			range.end,
-			op.props,
+			op,
 			clientArgs.referenceSequenceNumber,
 			clientArgs.clientId,
 			clientArgs.sequenceNumber,
@@ -686,6 +709,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 	private getValidOpRange(
 		op:
 			| IMergeTreeAnnotateMsg
+			| IMergeTreeAnnotateAdjustMsg
 			| IMergeTreeInsertMsg
 			| IMergeTreeRemoveMsg
 			// eslint-disable-next-line import/no-deprecated
@@ -767,11 +791,7 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 			| ISequencedDocumentMessage
 			| Pick<ISequencedDocumentMessage, "referenceSequenceNumber" | "clientId">
 			| undefined,
-	): {
-		clientId: number;
-		referenceSequenceNumber: number;
-		sequenceNumber: number;
-	} {
+	): IMergeTreeClientSequenceArgs {
 		// If there this no sequenced message, then the op is local
 		// and unacked, so use this clients sequenced args
 		//
@@ -907,7 +927,8 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 			switch (resetOp.type) {
 				case MergeTreeDeltaType.ANNOTATE: {
 					assert(
-						segment.propertyManager?.hasPendingProperties(resetOp.props) === true,
+						segment.propertyManager?.hasPendingProperties(resetOp.props ?? resetOp.adjust) ===
+							true,
 						0x036 /* "Segment has no pending properties" */,
 					);
 					// if the segment has been removed or obliterated, there's no need to send the annotate op
@@ -921,11 +942,18 @@ export class Client extends TypedEventEmitter<IClientEvents> {
 							(segment.localMovedSeq !== undefined &&
 								segment.movedSeq === UnassignedSequenceNumber))
 					) {
-						newOp = createAnnotateRangeOp(
-							segmentPosition,
-							segmentPosition + segment.cachedLength,
-							resetOp.props,
-						);
+						newOp =
+							resetOp.props === undefined
+								? createAdjustRangeOp(
+										segmentPosition,
+										segmentPosition + segment.cachedLength,
+										resetOp.adjust,
+									)
+								: createAnnotateRangeOp(
+										segmentPosition,
+										segmentPosition + segment.cachedLength,
+										resetOp.props,
+									);
 					}
 					break;
 				}

packages/dds/merge-tree/src/mergeTree.ts

@@ -94,6 +94,7 @@ import {
 	copyPropertiesAndManager,
 	PropertiesManager,
 	PropertiesRollback,
+	type PropsOrAdjust,
 } from "./segmentPropertiesManager.js";
 import { Side, type InteriorSequencePlace } from "./sequencePlace.js";
 import { SortedSegmentSet } from "./sortedSegmentSet.js";
@@ -277,6 +278,14 @@ export interface IMergeTreeOptions {
 	 * @defaultValue `false`
 	 */
 	mergeTreeEnableSidedObliterate?: boolean;
+
+	/**
+	 * Enables support for annotate adjust operations, which allow for specifying
+	 * a summand which is summed with the current value to compute the new value.
+	 *
+	 * @defaultValue `false`
+	 */
+	mergeTreeEnableAnnotateAdjust?: boolean;
 }
 
 /**
@@ -1895,7 +1904,7 @@ export class MergeTree {
 	 * Annotate a range with properties
 	 * @param start - The inclusive start position of the range to annotate
 	 * @param end - The exclusive end position of the range to annotate
-	 * @param props - The properties to annotate the range with
+	 * @param propsOrAdjust - The properties or adjustments to annotate the range with
 	 * @param refSeq - The reference sequence number to use to apply the annotate
 	 * @param clientId - The id of the client making the annotate
 	 * @param seq - The sequence number of the annotate operation
@@ -1905,33 +1914,37 @@ export class MergeTree {
 	public annotateRange(
 		start: number,
 		end: number,
-		props: PropertySet,
+		propsOrAdjust: PropsOrAdjust,
 		refSeq: number,
 		clientId: number,
 		seq: number,
 		opArgs: IMergeTreeDeltaOpArgs,
-
 		// eslint-disable-next-line import/no-deprecated
 		rollback: PropertiesRollback = PropertiesRollback.None,
 	): void {
+		if (propsOrAdjust.adjust !== undefined) {
+			errorIfOptionNotTrue(this.options, "mergeTreeEnableAnnotateAdjust");
+		}
+
 		this.ensureIntervalBoundary(start, refSeq, clientId);
 		this.ensureIntervalBoundary(end, refSeq, clientId);
 		const deltaSegments: IMergeTreeSegmentDelta[] = [];
 		const localSeq =
 			seq === UnassignedSequenceNumber ? ++this.collabWindow.localSeq : undefined;
 		// eslint-disable-next-line import/no-deprecated
 		let segmentGroup: SegmentGroup | undefined;
+		const opObj = propsOrAdjust.props ?? propsOrAdjust.adjust;
 		const annotateSegment = (segment: ISegmentLeaf): boolean => {
 			assert(
 				!Marker.is(segment) ||
-					!(reservedMarkerIdKey in props) ||
-					props.markerId === segment.properties?.markerId,
+					!(reservedMarkerIdKey in opObj) ||
+					opObj.markerId === segment.properties?.markerId,
 				0x5ad /* Cannot change the markerId of an existing marker */,
 			);
 
 			const propertyManager = (segment.propertyManager ??= new PropertiesManager());
 			const propertyDeltas = propertyManager.handleProperties(
-				{ props },
+				propsOrAdjust,
 				segment,
 				seq,
 				this.collabWindow.minSeq,
@@ -2409,12 +2422,11 @@ export class MergeTree {
 					this.annotateRange(
 						start,
 						start + segment.cachedLength,
-						props,
+						{ props },
 						UniversalSequenceNumber,
 						this.collabWindow.clientId,
 						UniversalSequenceNumber,
 						{ op: annotateOp },
-
 						PropertiesRollback.Rollback,
 					);
 					i++;

packages/dds/merge-tree/src/opBuilder.ts

@@ -14,9 +14,11 @@ import {
 	IMergeTreeObliterateMsg,
 	IMergeTreeRemoveMsg,
 	MergeTreeDeltaType,
+	type AdjustParams,
+	type IMergeTreeAnnotateAdjustMsg,
 	type IMergeTreeObliterateSidedMsg,
 } from "./ops.js";
-import { PropertySet } from "./properties.js";
+import { PropertySet, type MapLike } from "./properties.js";
 import { normalizePlace, Side, type SequencePlace } from "./sequencePlace.js";
 
 /**
@@ -66,6 +68,28 @@ export function createAnnotateRangeOp(
 	};
 }
 
+/**
+ * Creates the op for annotating the range with the provided properties
+ * @param start - The inclusive start position of the range to annotate
+ * @param end - The exclusive end position of the range to annotate
+ * @param props - The properties to annotate the range with
+ * @returns The annotate op
+ *
+ * @internal
+ */
+export function createAdjustRangeOp(
+	start: number,
+	end: number,
+	adjust: MapLike<AdjustParams>,
+): IMergeTreeAnnotateAdjustMsg {
+	return {
+		pos1: start,
+		pos2: end,
+		adjust: { ...adjust },
+		type: MergeTreeDeltaType.ANNOTATE,
+	};
+}
+
 /**
  * Creates the op to remove a range
  *

packages/dds/merge-tree/src/ops.ts

@@ -265,6 +265,7 @@ export type IMergeTreeDeltaOp =
 	| IMergeTreeInsertMsg
 	| IMergeTreeRemoveMsg
 	| IMergeTreeAnnotateMsg
+	| IMergeTreeAnnotateAdjustMsg
 	| IMergeTreeObliterateMsg
 	| IMergeTreeObliterateSidedMsg;
 

packages/dds/merge-tree/src/snapshotlegacy.ts

@@ -18,7 +18,7 @@ import {
 
 import { NonCollabClient, UnassignedSequenceNumber } from "./constants.js";
 import { MergeTree } from "./mergeTree.js";
-import { ISegment } from "./mergeTreeNodes.js";
+import { ISegment, type ISegmentLeaf } from "./mergeTreeNodes.js";
 import { matchProperties } from "./properties.js";
 import {
 	JsonSegmentSpecs,
@@ -193,7 +193,7 @@ export class SnapshotLegacy {
 
 	extractSync(): ISegment[] {
 		const collabWindow = this.mergeTree.collabWindow;
-		this.seq = collabWindow.minSeq;
+		const seq = (this.seq = collabWindow.minSeq);
 		this.header = {
 			segmentsTotalLength: this.mergeTree.getLength(
 				this.mergeTree.collabWindow.minSeq,
@@ -205,9 +205,9 @@ export class SnapshotLegacy {
 		let originalSegments = 0;
 
 		const segs: ISegment[] = [];
-		let prev: ISegment | undefined;
+		let prev: ISegmentLeaf | undefined;
 		const extractSegment = (
-			segment: ISegment,
+			segment: ISegmentLeaf,
 			pos: number,
 			refSeq: number,
 			clientId: number,
@@ -216,29 +216,26 @@ export class SnapshotLegacy {
 		): boolean => {
 			if (
 				segment.seq !== UnassignedSequenceNumber &&
-				segment.seq! <= this.seq! &&
+				segment.seq! <= seq &&
 				(segment.removedSeq === undefined ||
 					segment.removedSeq === UnassignedSequenceNumber ||
-					segment.removedSeq > this.seq!)
+					segment.removedSeq > seq)
 			) {
 				originalSegments += 1;
-				if (prev?.canAppend(segment) && matchProperties(prev.properties, segment.properties)) {
-					prev = prev.clone();
+				const properties =
+					segment.propertyManager?.getAtSeq(segment.properties, seq) ?? segment.properties;
+				if (prev?.canAppend(segment) && matchProperties(prev.properties, properties)) {
 					prev.append(segment.clone());
 				} else {
-					if (prev) {
-						segs.push(prev);
-					}
-					prev = segment;
+					prev = segment.clone();
+					prev.properties = properties;
+					segs.push(prev);
 				}
 			}
 			return true;
 		};
 
 		this.mergeTree.mapRange(extractSegment, this.seq, NonCollabClient, undefined);
-		if (prev) {
-			segs.push(prev);
-		}
 
 		this.segments = [];
 		let totalLength: number = 0;