@fluidframework/tree 2.91.0 → 2.92.0

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -447,6 +447,35 @@ export interface TreeArrayNode<
 	values(): IterableIterator<T>;
 }
 
+/**
+ * {@link (TreeArrayNode:interface)} with additional alpha APIs.
+ * @alpha @sealed
+ */
+export interface TreeArrayNodeAlpha<
+	TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe = ImplicitAllowedTypes,
+	out T = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? TreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+> extends TreeArrayNode<TAllowedTypes, T, TNew> {
+	/**
+	 * Removes existing item(s) and/or adds new item(s).
+	 * @param start - The index at which to start changing the array. If negative, it is treated as `array.length + start`.
+	 * Must be a positive in bounds index or a negative index such that `array.length + start` is a positive in bounds index.
+	 * @param deleteCount - The number of item(s) to remove. If not provided, it defaults to the end of the array.
+	 * Must be a non-negative integer no greater than the number of items from `start` to the end of the array.
+	 * @param items - The item(s) to insert at `start`.
+	 * @returns An array containing the item(s) that were removed.
+	 */
+	splice(
+		start: number,
+		deleteCount?: number,
+		...items: readonly (TNew | IterableTreeArrayContent<TNew>)[]
+	): T[];
+}
+
 /**
  * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  * @public
@@ -997,6 +1026,41 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 		editor.remove(removeStart, removeEnd - removeStart);
 	}
+	public splice(
+		start: number,
+		deleteCount?: number,
+		...items: Insertable<T>
+	): TreeNodeFromImplicitAllowedTypes<T>[] {
+		const length = this.length;
+		const actualStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+		const actualDeleteCount =
+			deleteCount === undefined
+				? length - actualStart
+				: Math.min(Math.max(deleteCount, 0), length - actualStart);
+		validateIndexRange(
+			actualStart,
+			actualStart + actualDeleteCount,
+			getSequenceField(this),
+			"TreeArrayNode.splice",
+		);
+		const removed: TreeNodeFromImplicitAllowedTypes<T>[] = [];
+		for (let index = actualStart; index < actualStart + actualDeleteCount; index++) {
+			removed.push(this.at(index) ?? oob());
+		}
+
+		const innerNode = getInnerNode(this);
+		const transaction = innerNode.isHydrated()
+			? innerNode.context.checkout.transaction
+			: undefined;
+		transaction?.start();
+		this.removeRange(actualStart, actualStart + actualDeleteCount);
+		if (items.length > 0) {
+			this.insertAt(actualStart, ...items);
+		}
+		transaction?.commit();
+		return removed;
+	}
+
 	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);

package/src/simple-tree/node-kinds/array/arrayNodeTypes.ts

@@ -14,7 +14,7 @@ import type {
 } from "../../core/index.js";
 import type { SchemaType, SimpleArrayNodeSchema } from "../../simpleSchema.js";
 
-import type { TreeArrayNode } from "./arrayNode.js";
+import type { TreeArrayNode, TreeArrayNodeAlpha } from "./arrayNode.js";
 
 /**
  * A schema for customizable {@link (TreeArrayNode:interface)}s.
@@ -37,6 +37,30 @@ export interface ArrayNodeCustomizableSchema<
 		>,
 		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
 
+/**
+ * A Schema for customizable {@link (TreeArrayNode:interface)}s with additional alpha APIs.
+ * @remarks
+ * Duplicates {@link ArrayNodeCustomizableSchema} with {@link TreeArrayNodeAlpha} as the node type,
+ * adding support for the alpha APIs on those nodes.
+ * @system @sealed @alpha
+ */
+export interface ArrayNodeCustomizableSchemaAlpha<
+	out TName extends string = string,
+	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	out ImplicitlyConstructable extends boolean = true,
+	out TCustomMetadata = unknown,
+> extends TreeNodeSchemaClass<
+			TName,
+			NodeKind.Array,
+			TreeArrayNodeAlpha<T> & WithType<TName, NodeKind.Array, T>,
+			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+			ImplicitlyConstructable,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
+
 /**
  * A schema for POJO emulation mode {@link (TreeArrayNode:interface)}s.
  * @system @sealed @alpha

package/src/simple-tree/node-kinds/array/index.ts

@@ -10,10 +10,12 @@ export {
 	TreeArrayNode,
 	type ReadonlyArrayNode,
 	type ArrayPlaceAnchor,
+	type TreeArrayNodeAlpha,
 	createArrayInsertionAnchor,
 } from "./arrayNode.js";
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	isArrayNodeSchema,

package/src/simple-tree/node-kinds/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	arraySchema,
@@ -12,6 +13,7 @@ export {
 	isArrayNodeSchema,
 	IterableTreeArrayContent,
 	TreeArrayNode,
+	type TreeArrayNodeAlpha,
 	type ReadonlyArrayNode,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,

package/src/text/textDomainFormatted.ts

@@ -6,8 +6,13 @@
 import { assert, compareArrays, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
-import { currentObserver } from "../feature-libraries/index.js";
+import {
+	EmptyKey,
+	forEachNodeSubsequence,
+	type FieldKey,
+	type ITreeCursorSynchronous,
+} from "../core/index.js";
+import { currentObserver, buildNodeComparator } from "../feature-libraries/index.js";
 import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	enumFromStrings,
@@ -24,7 +29,7 @@ import type {
 	TreeNodeFromImplicitAllowedTypes,
 	WithType,
 } from "../simple-tree/index.js";
-import { mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
+import { brand, mapIterable, validateIndex, validateIndexRange } from "../util/index.js";
 
 import { charactersFromString, type TextAsTree } from "./textDomain.js";
 
@@ -172,6 +177,12 @@ class TextNode
 			});
 		}
 	}
+	public getUniformRun(startIndex: number, endIndex?: number): number {
+		return this.content.getUniformRun(startIndex, endIndex);
+	}
+	public getString(startIndex: number, endIndex?: number): string {
+		return this.content.getString(startIndex, endIndex);
+	}
 }
 
 const defaultFormat = {
@@ -182,6 +193,8 @@ const defaultFormat = {
 	font: "Arial",
 } as const;
 
+const formatKey: FieldKey = brand("format");
+
 function textAtomsFromString(
 	value: string,
 	format: FormattedTextAsTree.CharacterFormat,
@@ -210,9 +223,10 @@ class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.Str
 		return result;
 	}
 
-	public charactersCopy(): string[] {
-		return this.withBorrowedSequenceCursor((cursor) =>
-			mapCursorField(cursor, () => {
+	private getCharactersSubarray(startIndex: number, endIndex: number): string[] {
+		return this.withBorrowedSequenceCursor((cursor) => {
+			const result: string[] = [];
+			forEachNodeSubsequence(cursor, startIndex, endIndex, () => {
 				debugAssert(
 					() =>
 						cursor.type === FormattedTextAsTree.StringAtom.identifier ||
@@ -243,14 +257,80 @@ class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.Str
 				}
 				cursor.exitNode();
 				cursor.exitField();
-				return content;
-			}),
-		);
+				result.push(content);
+			});
+			return result;
+		});
+	}
+
+	public charactersCopy(): string[] {
+		return this.getCharactersSubarray(0, this.length);
 	}
 
 	public fullString(): string {
 		return this.charactersCopy().join("");
 	}
+
+	public getString(startIndex: number, endIndex: number = this.length): string {
+		validateIndexRange(startIndex, endIndex, this, "FormattedTextAsTree.getString");
+		return this.getCharactersSubarray(startIndex, endIndex).join("");
+	}
+
+	public getUniformRun(startIndex: number, endIndex: number = this.length): number {
+		validateIndexRange(startIndex, endIndex, this, "FormattedTextAsTree.getUniformRun");
+		if (endIndex === startIndex) {
+			throw new UsageError("endIndex must be greater than startIndex for getUniformRun.");
+		}
+		const arrayLength = this.length;
+		return this.withBorrowedSequenceCursor((cursor) => {
+			cursor.enterNode(startIndex);
+
+			// Capture the content type of the first atom
+			cursor.enterField(EmptyKey);
+			cursor.enterNode(0);
+			const contentType = cursor.type;
+			cursor.exitNode();
+			cursor.exitField();
+
+			// Build a comparator from the format subtree of the first atom
+			// This compares by field key
+			cursor.enterField(formatKey);
+			cursor.enterNode(0);
+			const formatComparator = buildNodeComparator(cursor);
+			cursor.exitNode();
+			cursor.exitField();
+
+			let runLength = 1;
+			const limit = Math.min(endIndex, arrayLength) - startIndex;
+
+			while (runLength < limit && cursor.nextNode()) {
+				// Compare atom type
+				cursor.enterField(EmptyKey);
+				cursor.enterNode(0);
+				const typeMatches = cursor.type === contentType;
+				cursor.exitNode();
+				cursor.exitField();
+				if (!typeMatches) {
+					break;
+				}
+
+				// Compare format subtree using the compiled comparator
+				cursor.enterField(formatKey);
+				cursor.enterNode(0);
+				const formatMatches = formatComparator(cursor);
+				cursor.exitNode();
+				cursor.exitField();
+
+				if (formatMatches !== true) {
+					break;
+				}
+
+				runLength++;
+			}
+			cursor.exitNode();
+			return runLength;
+		});
+	}
 }
 
 /**
@@ -305,6 +385,11 @@ export namespace FormattedTextAsTree {
 		"h4",
 		"h5",
 		"li",
+		"ol",
+		"checked",
+		"unchecked",
+		"blockquote",
+		"codeBlock",
 	]);
 	/**
 	 * {@inheritdoc FormattedTextAsTree.(LineTag:variable)}
@@ -316,12 +401,16 @@ export namespace FormattedTextAsTree {
 	 * Unit in the string representing a new line character with line formatting.
 	 * @remarks
 	 * This aligns with how Quill represents line formatting.
-	 * Note that not all new lines will use this,
-	 * but only ones using this can have line specific formatting.
+	 * Quill formats line attributes (headers, list, blockquote, etc... ) on the newline character
+	 * and only lines using this atom can have line-specific formatting.
+	 * The optional indent level mirrors Quill's indent attribute,
+	 * which is applies to the line before the line break.
+	 * Any tagged line can be indented independently.
 	 * @internal
 	 */
 	export class StringLineAtom extends sf.object("StringLineAtom", {
 		tag: LineTag.schema,
+		indent: SchemaFactory.number,
 	}) {
 		public readonly content = "\n";
 	}
@@ -427,6 +516,19 @@ export namespace FormattedTextAsTree {
 			endIndex: number | undefined,
 			format: Partial<CharacterFormat>,
 		): void;
+
+		/**
+		 * Returns the length of the run of characters starting at `startIndex` which have the same formatting and atom type, up to `endIndex`.
+		 * @param startIndex - The starting index of the run.
+		 * @param endIndex - The ending index (exclusive) of the run. Defaults to the end of the text.
+		 */
+		getUniformRun(startIndex: number, endIndex?: number): number;
+		/**
+		 * Returns a substring of the text from `startIndex` to `endIndex`
+		 * @param startIndex - starting index (inclusive)
+		 * @param endIndex - Optional ending index (exclusive). Defaults to the end of the text.
+		 */
+		getString(startIndex: number, endIndex?: number): string;
 	}
 
 	/**

package/src/treeFactory.ts

@@ -16,7 +16,7 @@ import {
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { FluidClientVersion } from "./codec/index.js";
+import { FluidClientVersion, type FormatVersion } from "./codec/index.js";
 import {
 	SharedTreeKernel,
 	type ITreePrivate,
@@ -26,8 +26,10 @@ import {
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
 import {
-	editManagerFormatVersionSelectorForSharedBranches,
-	messageFormatVersionSelectorForSharedBranches,
+	editManagerCodecName,
+	EditManagerFormatVersion,
+	messageCodecName,
+	MessageFormatVersion,
 } from "./shared-tree-core/index.js";
 import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
 import type { ITree } from "./simple-tree/index.js";
@@ -222,6 +224,9 @@ function resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInte
 }
 
 const sharedBranchesOptions: SharedTreeOptionsInternal = {
-	messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
-	editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
+	writeVersionOverrides: new Map<string, FormatVersion>([
+		[editManagerCodecName, EditManagerFormatVersion.vSharedBranches],
+		[messageCodecName, MessageFormatVersion.vSharedBranches],
+	]),
+	allowPossiblyIncompatibleWriteVersionOverrides: true,
 };

package/src/util/referenceCounting.ts

@@ -39,7 +39,6 @@ export interface ReferenceCounted {
  * Base class to assist with implementing ReferenceCounted.
  */
 export abstract class ReferenceCountedBase implements ReferenceCounted {
-	// eslint-disable-next-line @typescript-eslint/prefer-readonly -- false positive; modified in multiple places
 	protected constructor(private refCount: number = 1) {}
 
 	public referenceAdded(count = 1): void {