@fluidframework/tree 2.81.0-374083 → 2.81.1

package/src/simple-tree/simpleSchema.ts

@@ -5,6 +5,7 @@
 
 import type { ValueSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+
 import type { NodeKind, SchemaUpgrade, SimpleNodeSchemaBase } from "./core/index.js";
 import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
 

package/src/simple-tree/treeSchema.ts

@@ -4,6 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import type { TreeNodeSchema } from "./core/index.js";
 import {
 	type FieldSchemaAlpha,

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -4,15 +4,11 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { filterIterable, hasSingle, oneFromIterable } from "../util/index.js";
 
-import type { FlexTreeNode } from "../feature-libraries/index.js";
-
-import type { ImplicitFieldSchema } from "./fieldSchema.js";
-import { normalizeFieldSchema, FieldKind } from "./fieldSchema.js";
 import {
 	CompatibilityLevel,
 	getKernel,
@@ -25,9 +21,10 @@ import {
 	UnhydratedFlexTreeNode,
 } from "./core/index.js";
 import { getUnhydratedContext } from "./createContext.js";
+import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fieldSchema.js";
 
 /**
- * Transforms an input {@link TypedNode} tree to a {@link FlexTreeNode}.
+ * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.
  * @param data - The input tree to be converted.
  * If the data is an unsupported value (e.g. NaN), a fallback value will be used when supported,
  * otherwise an error will be thrown.
@@ -52,10 +49,10 @@ import { getUnhydratedContext } from "./createContext.js";
  * Output should comply with the provided view schema, but this is not explicitly validated:
  * validation against stored schema (to guard against document corruption) is done elsewhere.
  */
-export function flexTreeFromInsertable<TIn extends InsertableContent | undefined>(
+export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(
 	data: TIn,
 	allowedTypes: ImplicitFieldSchema,
-): TIn extends undefined ? undefined : FlexTreeNode {
+): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {
 	const normalizedFieldSchema = normalizeFieldSchema(allowedTypes);
 
 	if (data === undefined) {
@@ -63,60 +60,35 @@ export function flexTreeFromInsertable<TIn extends InsertableContent | undefined
 		if (normalizedFieldSchema.kind !== FieldKind.Optional) {
 			throw new UsageError("Got undefined for non-optional field.");
 		}
-		return undefined as TIn extends undefined ? undefined : FlexTreeNode;
+		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 	}
 
-	const flexTree: FlexTreeNode = flexTreeFromInsertableNode(
+	const flexTree: UnhydratedFlexTreeNode = unhydratedFlexTreeFromInsertableNode(
 		data,
 		normalizedFieldSchema.allowedTypeSet,
 	);
 
-	return flexTree as TIn extends undefined ? undefined : FlexTreeNode;
+	return flexTree as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 }
 
 /**
- * Wrapper around {@link flexTreeFromInsertable} which always returns an unhydrated nodes (or undefined).
- * @remarks
- * This does not deeply check content is unhydrated.
- *
- * Once hybrid content is better supported, this should likely be removed as a simplification.
+ * Copy content from `data` into a UnhydratedFlexTreeNode.
  */
-export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(
-	data: TIn,
-	allowedTypes: ImplicitFieldSchema,
-): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {
-	const result = flexTreeFromInsertable(data, allowedTypes);
-	if (result === undefined) {
-		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
-	}
-	assert(result instanceof UnhydratedFlexTreeNode, "expected unhydrated node");
-	return result as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
-}
-
-/**
- * Copy content from `data` into a UnhydratedFlexTreeNode or return an existing node if `data` is a TreeNode.
- */
-export function flexTreeFromInsertableNode(
+export function unhydratedFlexTreeFromInsertableNode(
 	data: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-): FlexTreeNode {
+): UnhydratedFlexTreeNode {
 	if (isTreeNode(data)) {
 		const kernel = getKernel(data);
-		const inner = kernel.getInnerNode();
-		if (inner.parentField.parent.parent === undefined) {
+		const inner = kernel.getInnerNodeIfUnhydrated();
+		if (inner === undefined) {
+			// The node is already hydrated, meaning that it already got inserted into the tree previously
+			throw new UsageError("A node may not be inserted into the tree more than once");
+		} else {
 			if (!allowedTypes.has(kernel.schema)) {
 				throw new UsageError("Invalid schema for this context.");
 			}
-
-			if (inner.isHydrated()) {
-				// TODO: hook up event bubbling from hydrated to unhydrated tree.
-			}
-
 			return inner;
-		} else {
-			throw new UsageError(
-				"A node which already has a parent may not be used as part of a new tree.",
-			);
 		}
 	}
 

package/src/tableSchema.ts

@@ -3,9 +3,12 @@
  * Licensed under the MIT License.
  */
 
+/* eslint-disable @typescript-eslint/no-unsafe-member-access -- This file uses intentional `as any` casts to access hidden internal properties (cells, tableSchemaSymbol) */
+
 import { fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
+import { EmptyKey } from "./core/index.js";
 import { TreeAlpha } from "./shared-tree/index.js";
 import {
 	type FieldHasDefault,
@@ -35,7 +38,6 @@ import {
 	TreeNodeSchemaCore,
 } from "./simple-tree/index.js";
 import { validateIndex, validateIndexRange } from "./util/index.js";
-import { EmptyKey } from "./core/index.js";
 
 // Future improvement TODOs:
 // - Omit `cells` property from Row insertion type.

package/src/text/index.ts

@@ -4,3 +4,4 @@
  */
 
 export { TextAsTree } from "./textDomain.js";
+export { FormattedTextAsTree } from "./textDomainFormatted.js";

package/src/text/textDomain.ts

@@ -51,7 +51,7 @@ class TextNode
  * and provide a centralized place where validation could be added in the future if desired.
  * Additionally using this function consistently will make any refactors to support alternative character boundaries easier.
  */
-function charactersFromString(value: string): Iterable<string> {
+export function charactersFromString(value: string): Iterable<string> {
 	// Uses the string as an iterable of characters, so utf-16 surrogate pairs get grouped together correctly.
 	// Might be nice to call isWellFormed or toWellFormed here (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toWellFormed)
 	// But those are not widely supported yet.

package/src/text/textDomainFormatted.ts

@@ -0,0 +1,309 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { EmptyKey } from "../core/index.js";
+import {
+	enumFromStrings,
+	eraseSchemaDetails,
+	SchemaFactory,
+	SchemaFactoryAlpha,
+	TreeArrayNode,
+	TreeBeta,
+} from "../simple-tree/index.js";
+import type {
+	InsertableTypedNode,
+	TreeNode,
+	TreeNodeFromImplicitAllowedTypes,
+	WithType,
+} from "../simple-tree/index.js";
+import { mapIterable } from "../util/index.js";
+
+import { charactersFromString, type TextAsTree } from "./textDomain.js";
+
+const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted");
+
+class TextNode
+	extends sf.object("Text", {
+		content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
+	})
+	implements FormattedTextAsTree.Members
+{
+	public defaultFormat: FormattedTextAsTree.CharacterFormat =
+		new FormattedTextAsTree.CharacterFormat(defaultFormat);
+
+	public insertAt(index: number, additionalCharacters: string): void {
+		this.content.insertAt(
+			index,
+			TreeArrayNode.spread(textAtomsFromString(additionalCharacters, this.defaultFormat)),
+		);
+	}
+	public removeRange(index: number, length: number): void {
+		this.content.removeRange(index, length);
+	}
+	public characters(): Iterable<string> {
+		return mapIterable(this.content, (atom) => atom.content.content);
+	}
+	public fullString(): string {
+		return [...this.characters()].join("");
+	}
+
+	public static fromString(
+		value: string,
+		format?: FormattedTextAsTree.CharacterFormat,
+	): TextNode {
+		// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like it's not necessary here,
+		// but to reduce the risk of incorrect data interpretation, we actually ban this in the special case where the iterable is a string directly, which is the case here.
+		// Thus the array construction here is necessary to avoid a runtime error.
+		return new TextNode({
+			content: [
+				...textAtomsFromString(
+					value,
+					format ?? new FormattedTextAsTree.CharacterFormat(defaultFormat),
+				),
+			],
+		});
+	}
+
+	public charactersWithFormatting(): Iterable<FormattedTextAsTree.StringAtom> {
+		return this.content;
+	}
+	public insertWithFormattingAt(
+		index: number,
+		additionalCharacters: Iterable<InsertableTypedNode<typeof FormattedTextAsTree.StringAtom>>,
+	): void {
+		this.content.insertAt(index, TreeArrayNode.spread(additionalCharacters));
+	}
+	public formatRange(
+		startIndex: number,
+		length: number,
+		format: Partial<FormattedTextAsTree.CharacterFormat>,
+	): void {
+		for (let i = startIndex; i < startIndex + length; i++) {
+			const atom = this.content[i];
+			if (atom === undefined) {
+				throw new UsageError("Index out of bounds while formatting text range.");
+			}
+			for (const [key, value] of Object.entries(format) as [
+				keyof FormattedTextAsTree.CharacterFormat,
+				unknown,
+			][]) {
+				// Object.entries should only return string keyed enumerable own properties.
+				// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
+				assert(typeof key === "string", "Object.entries returned a non-string key.");
+				const f = FormattedTextAsTree.CharacterFormat.fields.get(key);
+				if (f === undefined) {
+					throw new UsageError(`Unknown format key: ${key}`);
+				}
+				// Ensures that if the input is a node, it is cloned before being inserted into the tree.
+				atom.format[key] = TreeBeta.clone(TreeBeta.create(f, value as never)) as never;
+			}
+		}
+	}
+}
+
+const defaultFormat = {
+	bold: false,
+	italic: false,
+	underline: false,
+	size: 12,
+	font: "Arial",
+} as const;
+
+function textAtomsFromString(
+	value: string,
+	format: FormattedTextAsTree.CharacterFormat,
+): Iterable<FormattedTextAsTree.StringAtom> {
+	const result = mapIterable(
+		charactersFromString(value),
+		(char) =>
+			new FormattedTextAsTree.StringAtom({
+				content: { content: char },
+				format: TreeBeta.clone<typeof FormattedTextAsTree.CharacterFormat>(format),
+			}),
+	);
+	return result;
+}
+
+class StringArray extends sf.array("StringArray", [() => FormattedTextAsTree.StringAtom]) {}
+
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * This has hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
+ * We will want to generalize this with a more generic schema factory function like with table.
+ * Then either that and/or the output from it can be package exported.
+ * This version is just an initial prototype.
+ * @internal
+ */
+export namespace FormattedTextAsTree {
+	/**
+	 * Formatting options for characters.
+	 * @internal
+	 */
+	export class CharacterFormat extends sf.objectAlpha("CharacterFormat", {
+		bold: SchemaFactory.boolean,
+		italic: SchemaFactory.boolean,
+		underline: SchemaFactory.boolean,
+		size: SchemaFactory.number,
+		font: SchemaFactory.string,
+	}) {}
+
+	/**
+	 * Unit in the string representing a single character.
+	 * @internal
+	 */
+	export class StringTextAtom extends sf.object("StringTextAtom", {
+		/**
+		 * The underlying text content of this atom.
+		 * @remarks
+		 * This is typically a single unicode codepoint, and thus may contain multiple utf-16 surrogate pair code units.
+		 * Using longer strings is still valid. For example, so users might store whole grapheme clusters here, or even longer sections of text.
+		 * Anything combined into a single atom will be treated atomically, and can not be partially selected or formatted.
+		 * Using larger atoms and splitting them as needed is NOT a recommended approach, since this will result in poor merge behavior for concurrent edits.
+		 * Instead atoms should always be the smallest unit of text which will be independently selected, moved or formatted.
+		 * @privateRemarks
+		 * This content logically represents the whole atom's content, so using {@link EmptyKey} makes sense to help indicate that.
+		 */
+		content: SchemaFactory.required([SchemaFactory.string], { key: EmptyKey }),
+	}) {}
+
+	/**
+	 * Tag with which a line in text can be formatted from HTML.
+	 * @internal
+	 */
+	export const LineTag = enumFromStrings(sf.scopedFactory("lineTag"), [
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"li",
+	]);
+	/**
+	 * {@inheritdoc FormattedTextAsTree.(LineTag:variable)}
+	 * @internal
+	 */
+	export type LineTag = TreeNodeFromImplicitAllowedTypes<typeof LineTag.schema>;
+
+	/**
+	 * 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.
+	 * @internal
+	 */
+	export class StringLineAtom extends sf.object("StringLineAtom", {
+		tag: LineTag.schema,
+	}) {
+		public readonly content = "\n";
+	}
+
+	/**
+	 * Types of "atoms" that make up the text.
+	 * @internal
+	 */
+	export const StringAtomContent = [StringTextAtom, StringLineAtom] as const;
+	/**
+	 * {@inheritdoc FormattedTextAsTree.(StringAtomContent:variable)}
+	 * @internal
+	 */
+	export type StringAtomContent = TreeNodeFromImplicitAllowedTypes<typeof StringAtomContent>;
+
+	/**
+	 * A unit of the text, with formatting.
+	 * @internal
+	 */
+	export class StringAtom extends sf.object("StringAtom", {
+		content: SchemaFactory.required(StringAtomContent, { key: EmptyKey }),
+		format: CharacterFormat,
+	}) {}
+
+	/**
+	 * Statics for text nodes.
+	 * @internal
+	 */
+	export interface Statics {
+		/**
+		 * Construct a {@link FormattedTextAsTree.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.
+		 * @remarks This combines pairs of utf-16 surrogate code units into single characters as appropriate.
+		 */
+		fromString(value: string): Tree;
+	}
+
+	/**
+	 * Interface for a text node.
+	 * @remarks
+	 * The string is broken up into substrings which are referred to as 'characters'.
+	 * Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit.
+	 * This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings,
+	 * and avoids the issue where indexing a string and iterating it segment the string differently.
+	 * This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do):
+	 * applications will likely want to include higher level segmentation logic
+	 * which might differ between operations like delete
+	 * (which often operates on something in between unicode code points and grapheme clusters)
+	 * and navigation/selection (which typically uses grapheme clusters).
+	 *
+	 * @see {@link FormattedTextAsTree.Statics.fromString} for construction.
+	 * @see {@link FormattedTextAsTree.(Tree:type)} for schema.
+	 * @internal
+	 */
+	export interface Members extends TextAsTree.Members {
+		/**
+		 * Format to use by default for text inserted with non-formatted APIs.
+		 * @remarks
+		 * This is not persisted in the tree, and observation of it is not tracked by the tree observation tracking.
+		 * @privateRemarks
+		 * Opt this into observation tracking.
+		 */
+		defaultFormat: CharacterFormat;
+
+		/**
+		 * Gets an iterable over the characters currently in the text.
+		 * @remarks
+		 * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.
+		 */
+		charactersWithFormatting(): Iterable<StringAtom>;
+
+		/**
+		 * Insert a range of characters into the string based on character index.
+		 * @remarks
+		 * See {@link (TreeArrayNode:interface).insertAt} for more details on the behavior.
+		 * See {@link FormattedTextAsTree.Statics.fromString} for how the `additionalCharacters` string is broken into characters.
+		 * @privateRemarks
+		 * If we provide ways to customize character boundaries, that could be handled here by taking in an Iterable<string> instead of a string.
+		 * Doing this currently would enable insertion of text with different character boundaries than the existing text,
+		 * which would violate the currently documented character boundary invariants.
+		 *
+		 * Another option would be to take an approach like Table,
+		 * where the user of the API uses a factory function to generate the schema, and can inject custom logic, like a string character iterator.
+		 */
+		insertWithFormattingAt(
+			index: number,
+			additionalCharacters: Iterable<InsertableTypedNode<typeof StringAtom>>,
+		): void;
+
+		/**
+		 * Apply formatting to a range of characters based on character index.
+		 * @param startIndex - The starting index of the range to format.
+		 * @param length - The number of characters to format.
+		 * @param format - The formatting to apply to the specified range.
+		 */
+		formatRange(startIndex: number, length: number, format: Partial<CharacterFormat>): void;
+	}
+
+	/**
+	 * Schema for a text node.
+	 * @remarks
+	 * See {@link FormattedTextAsTree.Members} for the API.
+	 * See {@link FormattedTextAsTree.Statics} for static APIs on this Schema, including construction.
+	 * @internal
+	 */
+	export const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);
+	export type Tree = Members & TreeNode & WithType<"com.fluidframework.text.formatted.Text">;
+}

package/src/treeFactory.ts

@@ -16,6 +16,7 @@ import {
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
+import { FluidClientVersion } from "./codec/index.js";
 import {
 	SharedTreeKernel,
 	type ITreePrivate,
@@ -24,16 +25,13 @@ import {
 	type SharedTreeOptionsInternal,
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
-import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
-import type { ITree } from "./simple-tree/index.js";
-import { Breakable, copyProperty } from "./util/index.js";
-import { FluidClientVersion } from "./codec/index.js";
 import {
-	editManagerFormatVersionSelectorForDetachedRootEditing,
 	editManagerFormatVersionSelectorForSharedBranches,
-	messageFormatVersionSelectorForDetachedRootEditing,
 	messageFormatVersionSelectorForSharedBranches,
 } from "./shared-tree-core/index.js";
+import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
+import type { ITree } from "./simple-tree/index.js";
+import { Breakable, copyProperty } from "./util/index.js";
 
 /**
  * {@link ITreePrivate} extended with ISharedObject.
@@ -214,15 +212,12 @@ export function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInt
 }
 
 function resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {
-	if (options.enableSharedBranches === true && options.enableDetachedRootEditing === true) {
-		throw new UsageError("enableDetachRootEditing cannot be used with enableSharedBranches.");
-	}
-	if (options.enableSharedBranches === true) {
+	const enableSharedBranches = options.enableSharedBranches ?? false;
+
+	if (enableSharedBranches) {
 		return sharedBranchesOptions;
 	}
-	if (options.enableDetachedRootEditing === true) {
-		return detachRootEditingOptions;
-	}
+
 	return {};
 }
 
@@ -230,8 +225,3 @@ const sharedBranchesOptions: SharedTreeOptionsInternal = {
 	messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
 	editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
 };
-const detachRootEditingOptions: SharedTreeOptionsInternal = {
-	messageFormatSelector: messageFormatVersionSelectorForDetachedRootEditing,
-	editManagerFormatSelector: editManagerFormatVersionSelectorForDetachedRootEditing,
-	canMakeDetachedRootEdits: true,
-};

package/src/util/bTreeUtils.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
+import { debugAssert } from "@fluidframework/core-utils/internal";
 import { BTree, defaultComparator, type DefaultComparable } from "@tylerbu/sorted-btree-es6";
 
 import { brand, type Brand } from "./brand.js";
-import { debugAssert } from "@fluidframework/core-utils/internal";
 
 /**
  * A BTree which uses tuples (arrays) as the key.

package/src/util/index.ts

@@ -134,10 +134,7 @@ export {
 export {
 	RangeMap,
 	type RangeQueryResult,
-	type RangeQueryResultFragment,
-	type RangeQueryEntry,
 	newIntegerRangeMap,
-	areAdjacentIntegerRanges,
 } from "./rangeMap.js";
 
 export {