@fluidframework/tree 2.80.0 → 2.81.0-374083

package/lib/simple-tree/prepareForInsertion.js.map

@@ -1 +1 @@
-{"version":3,"file":"prepareForInsertion.js","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tSchemaAndPolicy,\n\tIForestSubscription,\n\tUpPath,\n\tFieldKey,\n\tDetachedField,\n\tTreeFieldStoredSchema,\n\tTreeTypeSet,\n} from \"../core/index.js\";\nimport {\n\ttype FlexTreeContext,\n\tgetSchemaAndPolicy,\n\ttype FlexTreeHydratedContextMinimal,\n\tFieldKinds,\n\ttype FlexibleFieldContent,\n\ttype FlexibleNodeContent,\n\tthrowOutOfSchema,\n\tflexTreeSlot,\n\tContextSlot,\n\tgetOrCreateHydratedFlexTreeNode,\n\tassertFlexTreeEntityNotFreed,\n} from \"../feature-libraries/index.js\";\nimport type { ImplicitFieldSchema } from \"./fieldSchema.js\";\nimport {\n\ttype InsertableContent,\n\tunhydratedFlexTreeFromInsertable,\n} from \"./unhydratedFlexTreeFromInsertable.js\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { brand, type Mutable } from \"../util/index.js\";\nimport {\n\tgetKernel,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNode,\n\ttype UnhydratedFlexTreeNode,\n} from \"./core/index.js\";\nimport { debugAssert, fail, oob } from \"@fluidframework/core-utils/internal\";\nimport { isFieldInSchema } from \"../feature-libraries/index.js\";\n\n/**\n * For now, schema validation for inserted content is always enabled.\n * @remarks\n * If this ends up being too much of a performance overhead, AND nothing depends on it (like staged allowed types likely will),\n * this could be changed.\n */\nconst validateSchema = true;\n\n/**\n * Prepare content from a user for insertion into a tree.\n * @remarks\n * This validates and converts the input, and if necessary invokes {@link prepareContentForHydration}.\n *\n * The next edit made to `destinationContext`'s forest must be the creation of a detached field containing this content,\n * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.\n */\nexport function prepareForInsertion<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeFieldStoredSchema,\n): TIn extends undefined ? undefined : FlexibleNodeContent {\n\treturn prepareForInsertionContextless(\n\t\tdata,\n\t\tschema,\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\tdestinationSchema,\n\t);\n}\n\n/**\n * {@link prepareForInsertion} but batched for array content.\n * @remarks\n * This is for inserting items into an array, not a inserting a {@link TreeArrayNode} (that would use {@link prepareForInsertion}).\n *\n * The next edits made to `destinationContext`'s forest must be the creation of a detached field.\n * One edit for each item in `data`, in order.\n *\n * @privateRemarks\n * This has to be done as a single operation for all items in data\n * (as opposed to mapping {@link prepareForInsertion} over the array)\n * due to how the eventing in prepareContentForHydration works.\n */\nexport function prepareArrayContentForInsertion(\n\tdata: readonly InsertableContent[],\n\tschema: ImplicitAllowedTypes,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeTypeSet,\n): FlexibleFieldContent {\n\tconst mapTrees: UnhydratedFlexTreeNode[] = data.map((item) =>\n\t\tunhydratedFlexTreeFromInsertable(item, schema),\n\t);\n\n\tvalidateAndPrepare(\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\t{\n\t\t\tkind: FieldKinds.sequence.identifier,\n\t\t\ttypes: destinationSchema,\n\t\t\tpersistedMetadata: undefined,\n\t\t},\n\t\tmapTrees,\n\t);\n\n\treturn mapTrees;\n}\n\n/**\n * Split out from {@link prepareForInsertion} as to allow use without a context.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n *\n * @remarks\n * Adding this entry point is a workaround for initialize not currently having a context.\n */\nexport function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tdestinationSchema: TreeFieldStoredSchema,\n\tscheduleHydrationOverride?: HydrationScheduler,\n): TIn extends undefined ? undefined : FlexibleNodeContent {\n\tconst mapTree = unhydratedFlexTreeFromInsertable(data, schema);\n\n\tconst contentArray = mapTree === undefined ? [] : [mapTree];\n\tvalidateAndPrepare(\n\t\tschemaAndPolicy,\n\t\thydratedData,\n\t\tdestinationSchema,\n\t\tcontentArray,\n\t\tscheduleHydrationOverride,\n\t);\n\n\treturn mapTree;\n}\n\n/**\n * If hydrating, do a final validation against the schema and prepare the content for hydration.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n */\nfunction validateAndPrepare(\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tfieldSchema: TreeFieldStoredSchema,\n\tmapTrees: readonly UnhydratedFlexTreeNode[],\n\tscheduleHydrationOverride?: HydrationScheduler,\n): void {\n\tif (hydratedData !== undefined) {\n\t\t// Run `prepareContentForHydration` before walking the tree in `isFieldInSchema`.\n\t\t// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),\n\t\t// they were already creating used the more specific context we have access to from `hydratedData`.\n\t\tprepareContentForHydration(\n\t\t\tmapTrees,\n\t\t\tscheduleHydrationOverride ??\n\t\t\t\t((batch, doHydration) =>\n\t\t\t\t\tscheduleHydration(batch, hydratedData.checkout.forest, doHydration)),\n\t\t\thydratedData,\n\t\t);\n\t\t// TODO: AB#45723\n\t\t// Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.\n\t\t// We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).\n\t\t// Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.\n\t\tif (validateSchema === true) {\n\t\t\tisFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy, throwOutOfSchema);\n\t\t}\n\t}\n}\n\n/**\n * The path from the included node to the root of the content tree it was inserted as part of.\n */\ninterface RelativeNodePath {\n\treadonly path: UpPath;\n\treadonly node: TreeNode;\n}\n\n/**\n * {@link RelativeNodePath}s for every {@link TreeNode} in the content tree inserted as an atomic operation.\n */\ninterface LocatedNodesBatch {\n\t/**\n\t * UpPath shared by all {@link RelativeNodePath}s in this batch corresponding to the root of the inserted content.\n\t */\n\treadonly rootPath: Mutable<UpPath>;\n\treadonly paths: RelativeNodePath[];\n}\n\n/**\n * A dummy key value used in {@link LocatedNodesBatch.rootPath} which will be replaced with the actual detached field once it is known.\n */\nconst placeholderKey: DetachedField & FieldKey = brand(\"placeholder\" as const);\n\n/**\n * Records any {@link TreeNode}s in the given `content` tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.\n * Additionally populates any {@link UnhydratedFlexTreeField.pendingDefault}s using the provided `context`.\n *\n * @remarks If the content tree contains has any associated {@link TreeNode}s, this function must be called just prior to inserting the content into the tree.\n * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.\n * The insertion of `content` must occur or else this function will cause memory leaks.\n *\n * Exported for testing purposes: otherwise should not be used outside this module.\n * @param content - the content subsequence to be inserted, of which might deeply contain {@link TreeNode}s which need to be hydrated.\n * @param forest - the forest the content is being inserted into.\n */\nexport function prepareContentForHydration(\n\tcontent: readonly UnhydratedFlexTreeNode[],\n\tscheduler: HydrationScheduler,\n\tcontext: FlexTreeHydratedContextMinimal,\n): void {\n\tconst batches: LocatedNodesBatch[] = [];\n\tfor (const item of content) {\n\t\tconst batch: LocatedNodesBatch = {\n\t\t\trootPath: {\n\t\t\t\tparent: undefined,\n\t\t\t\tparentField: placeholderKey,\n\t\t\t\tparentIndex: 0,\n\t\t\t},\n\t\t\tpaths: [],\n\t\t};\n\t\tbatches.push(batch);\n\t\twalkMapTree(\n\t\t\titem,\n\t\t\tbatch.rootPath,\n\t\t\t(p, node) => {\n\t\t\t\tbatch.paths.push({ path: p, node });\n\t\t\t},\n\t\t\tcontext,\n\t\t);\n\t}\n\n\tconst doHydration = hydrator(batches, context.checkout.forest);\n\tscheduler(batches, doHydration);\n}\n\nfunction walkMapTree(\n\troot: UnhydratedFlexTreeNode,\n\tpath: UpPath,\n\tonVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,\n\tcontext: FlexTreeHydratedContextMinimal,\n): void {\n\tif (root.parentField.parent.parent !== undefined) {\n\t\tthrow new UsageError(\n\t\t\t\"Attempted to insert a node which is already under a parent. If this is desired, remove the node from its parent before inserting it elsewhere.\",\n\t\t);\n\t}\n\n\ttype Next = [path: UpPath, tree: UnhydratedFlexTreeNode];\n\tconst nexts: Next[] = [];\n\tfor (let next: Next | undefined = [path, root]; next !== undefined; next = nexts.pop()) {\n\t\tconst [p, node] = next;\n\t\tif (node !== undefined) {\n\t\t\tconst treeNode = node.treeNode;\n\t\t\tif (treeNode !== undefined) {\n\t\t\t\tonVisitTreeNode(p, treeNode);\n\t\t\t}\n\t\t}\n\n\t\tfor (const [key, field] of node.allFieldsLazy) {\n\t\t\tfield.fillPendingDefaults(context);\n\t\t\tfor (const [i, child] of field.children.entries()) {\n\t\t\t\tnexts.push([\n\t\t\t\t\t{\n\t\t\t\t\t\tparent: p,\n\t\t\t\t\t\tparentField: key,\n\t\t\t\t\t\tparentIndex: i,\n\t\t\t\t\t},\n\t\t\t\t\tchild,\n\t\t\t\t]);\n\t\t\t}\n\t\t}\n\t}\n}\n\n/**\n * A function which can schedule hydration of batches of nodes to occur at a later time (which must be after they have been inserted into the tree).\n */\ntype HydrationScheduler = (\n\tlocatedNodes: readonly LocatedNodesBatch[],\n\t/**\n\t * Does the actual hydration. Should be called for each index in `locatedNodes` once the corresponding content has been inserted into the tree.\n\t */\n\tdoHydration: Hydrator,\n) => void;\n\n/**\n * Does the actual hydration.\n * The provided `attachPath` is the path the content is currently under (where it was attached in the tree).\n */\ntype Hydrator = (batch: LocatedNodesBatch, attachPath: UpPath) => void;\n\n/**\n * Register events which will hydrate batches of nodes when they are inserted.\n * The next edits to forest must be their insertions, in order, or data corruption can occur.\n * @param locatedNodes - the nodes to register with the forest.\n * Each index in this array expects its content to be added and produce its own `afterRootFieldCreated` event.\n * If array subsequence insertion is optimized to produce a single event, this will not work correctly as is, and will need to be modified to take in a single {@link LocatedNodesBatch}.\n */\nfunction scheduleHydration(\n\tlocatedNodes: readonly LocatedNodesBatch[],\n\tforest: IForestSubscription,\n\tdoHydration: Hydrator,\n): void {\n\t// Only subscribe to the event if there is at least one TreeNode tree to hydrate - this is not the case when inserting an empty array [].\n\tif (locatedNodes.length > 0) {\n\t\t// Creating a new array emits one event per element in the array, so listen to the event once for each element\n\t\tlet index = 0;\n\t\tconst off = forest.events.on(\"afterRootFieldCreated\", (fieldKey) => {\n\t\t\t// Indexing is safe here because of the length check above. This assumes the array has not been modified which should be the case.\n\t\t\tconst batch = locatedNodes[index] ?? oob();\n\t\t\tdoHydration(batch, { parent: undefined, parentField: fieldKey, parentIndex: 0 });\n\t\t\tif (++index === locatedNodes.length) {\n\t\t\t\toff();\n\t\t\t}\n\t\t});\n\t}\n}\n\n/**\n * Implementation of {@link Hydrator}.\n */\nfunction hydrator(\n\tlocatedNodes: readonly LocatedNodesBatch[],\n\tforest: IForestSubscription,\n): (batch: LocatedNodesBatch, attachedPath: UpPath) => void {\n\treturn (batch: LocatedNodesBatch, attachedPath: UpPath) => {\n\t\tconst context = forest.anchors.slots.get(ContextSlot) ?? fail(0xb41 /* missing context */);\n\n\t\t// Modify paths in batch to point to correct location:\n\t\tdebugAssert(() => batch.rootPath.parentField === placeholderKey);\n\t\tbatch.rootPath.parentField = attachedPath.parentField;\n\t\tbatch.rootPath.parent = attachedPath.parent;\n\t\tbatch.rootPath.parentIndex = attachedPath.parentIndex;\n\n\t\t// To hydrate a TreeNode, it must be associated with a HydratedFlexTreeNode.\n\t\t// Find or create one as necessary.\n\t\tfor (const { path, node } of batch.paths) {\n\t\t\tconst anchor = forest.anchors.track(path);\n\t\t\tconst anchorNode = forest.anchors.locate(anchor) ?? fail(0xc7b /* missing anchor */);\n\n\t\t\tlet flexNode = anchorNode.slots.get(flexTreeSlot);\n\t\t\tif (flexNode === undefined) {\n\t\t\t\t// the flex node must be created\n\t\t\t\tconst cursor = forest.allocateCursor(\"getFlexNode\");\n\t\t\t\tforest.moveCursorToPath(anchorNode, cursor);\n\n\t\t\t\tflexNode = getOrCreateHydratedFlexTreeNode(context, cursor);\n\t\t\t\tcursor.free();\n\t\t\t\tassertFlexTreeEntityNotFreed(flexNode);\n\t\t\t}\n\n\t\t\tgetKernel(node).hydrate(flexNode);\n\t\t\tforest.anchors.forget(anchor);\n\t\t}\n\t};\n}\n"]}
+{"version":3,"file":"prepareForInsertion.js","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type {\n\tSchemaAndPolicy,\n\tFieldKey,\n\tTreeFieldStoredSchema,\n\tTreeTypeSet,\n} from \"../core/index.js\";\nimport { dummyRoot, keyAsDetachedField, rootFieldKey } from \"../core/index.js\";\nimport {\n\ttype FlexTreeContext,\n\tgetSchemaAndPolicy,\n\ttype FlexTreeHydratedContextMinimal,\n\tFieldKinds,\n\ttype FlexibleFieldContent,\n\ttype FlexibleNodeContent,\n\ttype FlexTreeNode,\n\tcursorForMapTreeField,\n\tthrowOutOfSchema,\n\ttype TreeChunk,\n\ttype HydratedFlexTreeNode,\n\ttype MinimalMapTreeNodeView,\n\ttype FlexTreeField,\n\ttype DetachedRootsLocation,\n} from \"../feature-libraries/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"./fieldSchema.js\";\nimport {\n\ttype InsertableContent,\n\tflexTreeFromInsertable,\n} from \"./unhydratedFlexTreeFromInsertable.js\";\nimport {\n\tcreateField,\n\tgetInnerNode,\n\tgetKernel,\n\tisTreeNode,\n\tUnhydratedFlexTreeNode,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNode,\n\ttype UnhydratedFlexTreeField,\n} from \"./core/index.js\";\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\nimport { combineChunks, isFieldInSchema } from \"../feature-libraries/index.js\";\nimport { getUnhydratedContext } from \"./createContext.js\";\nimport { convertField } from \"./toStoredSchema.js\";\nimport type { SchemaType, SimpleFieldSchema } from \"./simpleSchema.js\";\n\n/**\n * For now, schema validation for inserted content is always enabled.\n * @remarks\n * If this ends up being too much of a performance overhead, AND nothing depends on it (like staged allowed types likely will),\n * this could be changed.\n */\nconst validateSchema = true;\n\n// IDEA:\n// Have prepareForInsertion return a TreeChunk, and a function which should be called after its insertion with the path to its location (as Inner node?)\n\nfunction isHydrated(node: InsertableContent): boolean {\n\treturn isTreeNode(node) && getKernel(node).isHydrated();\n}\n\nfunction assertIsDetachedFlexTreeNode(node: FlexTreeNode): void {\n\tif (\n\t\tnode.parentField.parent.parent !== undefined ||\n\t\tnode.parentField.parent.key === rootFieldKey\n\t) {\n\t\tthrow new UsageError(\n\t\t\t\"Can only attach a detached node (i.e., a root with TreeStatus.Removed status)\",\n\t\t);\n\t}\n}\n\n/**\n * Prepare content from a user for insertion into a tree.\n * @remarks\n * This validates and converts the input, and if necessary invokes {@link prepareContentForHydration}.\n *\n * The next edit made to `destinationContext`'s forest must be the creation of a detached field containing this content,\n * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.\n */\nexport function prepareForInsertion<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeFieldStoredSchema,\n): TIn extends undefined ? undefined : FlexibleNodeContent {\n\tif (data !== undefined && isHydrated(data)) {\n\t\tconst treeNode = getInnerNode(data as TreeNode);\n\t\tassertIsDetachedFlexTreeNode(treeNode);\n\t\treturn treeNode as TIn extends undefined ? undefined : FlexibleNodeContent;\n\t}\n\n\tconst content = prepareForInsertionContextlessInternal(\n\t\tdata,\n\t\tschema,\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\tdestinationSchema,\n\t);\n\n\tassert(content.toAttach !== undefined, \"Expected toAttach to be defined\");\n\tassert(content.toAttach.length < 2, \"Expected toAttach to be a single element on none\");\n\n\t// TODO: when supporting back compat to not edit detached fields, caller will have to finalize after attaching to in document location.\n\tcontent.finalize(content.toAttach);\n\treturn (\n\t\tcontent.toAttach.length === 0 ? undefined : content.toAttach[0]\n\t) as TIn extends undefined ? undefined : FlexibleNodeContent;\n}\n\n/**\n * {@link prepareForInsertion} but batched for array content.\n * @remarks\n * This is for inserting items into an array, not a inserting a {@link TreeArrayNode} (that would use {@link prepareForInsertion}).\n *\n * The next edits made to `destinationContext`'s forest must be the creation of a detached field.\n * One edit for each item in `data`, in order.\n *\n * @privateRemarks\n * This has to be done as a single operation for all items in data\n * (as opposed to mapping {@link prepareForInsertion} over the array)\n * due to how the eventing in prepareContentForHydration works.\n */\nexport function prepareArrayContentForInsertion(\n\tdata: readonly InsertableContent[],\n\tschema: ImplicitAllowedTypes,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeTypeSet,\n): FlexibleFieldContent {\n\tconst hasHydratedData = data.some(isHydrated);\n\tif (hasHydratedData) {\n\t\tconst hasUnhydratedData = data.some((item) => !isHydrated(item));\n\t\tif (hasUnhydratedData) {\n\t\t\tthrow new UsageError(\"Mixed hydrated and unhydrated data not supported\");\n\t\t}\n\t\tconst treeNodes = data.map((item) => getInnerNode(item as TreeNode));\n\t\tfor (const node of treeNodes) {\n\t\t\tassertIsDetachedFlexTreeNode(node);\n\t\t}\n\t\treturn treeNodes;\n\t}\n\n\tconst mapTrees: FlexTreeNode[] = data.map((item) => flexTreeFromInsertable(item, schema));\n\n\tconst fieldSchema = convertField(\n\t\tnormalizeFieldSchema(schema) as unknown as SimpleFieldSchema<SchemaType.Stored>,\n\t\t// permissiveStoredSchemaGenerationOptions,\n\t);\n\n\tconst normalizedFieldSchema = normalizeFieldSchema(schema);\n\tconst field = createField(\n\t\tgetUnhydratedContext(normalizedFieldSchema).flexContext,\n\t\tfieldSchema.kind,\n\t\tdummyRoot,\n\t\tmapTrees,\n\t);\n\n\tconst content = validateAndPrepare(\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\t{\n\t\t\tkind: FieldKinds.sequence.identifier,\n\t\t\ttypes: destinationSchema,\n\t\t\tpersistedMetadata: undefined,\n\t\t},\n\t\tfield,\n\t);\n\n\tassert(content.toAttach !== undefined, \"Expected toAttach to be defined\");\n\n\t// TODO: when supporting back compat to not edit detached fields, caller will have to finalize after attaching to in document location.\n\tcontent.finalize(content.toAttach);\n\treturn content.toAttach;\n}\n\nexport interface PreparedContent {\n\t/**\n\t * New content which to be attached. Rooted in detached fields.\n\t * @remarks\n\t * When destination is a hydrated context, this will contain hydrated flex tree nodes.\n\t * The corresponding TreeNodes will not yet be hydrated, and some subtrees may be in separate detached fields.\n\t *\n\t * TODO: Eventually, this should be a single detached field, not an array of nodes each in their own detached field.\n\t */\n\treadonly toAttach?: readonly FlexTreeNode[];\n\n\t/**\n\t * Location of toAttach.\n\t * @remarks\n\t * This is redundant with `toAttach.key` but in a different format/type.\n\t * Only provided for hydrated destinations.\n\t */\n\treadonly rootsLocations?: DetachedRootsLocation;\n\n\t/**\n\t * Finalizes the prepared content. Moves in missing subtrees from detached fields, and hydrates TreeNodes as needed.\n\t *\n\t * @param attached - The nodes that were attached to the tree.\n\t *\n\t * @remarks\n\t * Call this exactly once, after `toAttach` has been attached to its final location.\n\t * There must be no app facing events between creation of this `PreparedContent` and its finalization since during this time TreeNodes may be in an invalid state (inner node hydrated, but TreeNode not).\n\t *\n\t * The implementation of this must not assume the context provided to `prepareForInsertion*` is still valid.\n\t */\n\treadonly finalize: (attached: readonly FlexTreeNode[]) => void;\n}\n\n/**\n * This exists to handle the required root initialize case where the flex tree nodes get invalidated by a schema change and thus new node instances need to be provided.\n */\nexport interface PreparedContentInitialize extends PreparedContent {\n\t/**\n\t * {@inheritDoc PreparedContent.rootIds}\n\t */\n\treadonly rootsLocations: DetachedRootsLocation;\n}\n\n/**\n * This exists to handle the required root initialize case where the flex tree nodes get invalidated by a schema change and thus new node instances need to be provided.\n */\nexport interface PreparedContentRegular extends PreparedContent {\n\t/**\n\t * {@inheritDoc PreparedContent.toAttach}\n\t */\n\treadonly toAttach: readonly FlexTreeNode[];\n\n\t/**\n\t * {@link PreparedContent.finalize} but without `attached` parameter: assumes `toAttach` is the same is still valid and uses that.\n\t */\n\treadonly finalize: () => void;\n}\n\n/**\n * Split out from {@link prepareForInsertion} as to allow use without a context.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n *\n * @remarks\n * Adding this entry point is a workaround for initialize not currently having a context.\n */\nexport function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal,\n\tdestinationSchema: TreeFieldStoredSchema,\n): PreparedContentInitialize {\n\tconst final = prepareForInsertionContextlessInternal(\n\t\tdata,\n\t\tschema,\n\t\tschemaAndPolicy,\n\t\thydratedData,\n\t\tdestinationSchema,\n\t);\n\tassert(final.rootsLocations !== undefined, \"Expected rootIds to be defined\");\n\tassert(\n\t\tfinal.rootsLocations.length <= 1,\n\t\t\"Expected at most one node to be returned from prepareForInsertionContextless\",\n\t);\n\n\t// For some reason TypeScript can't figure out that final.rootsLocations is defined unless we handle is separately.\n\treturn { ...final, rootsLocations: final.rootsLocations };\n}\n\n/**\n * Split out from {@link prepareForInsertion} as to allow use without a context.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n */\nfunction prepareForInsertionContextlessInternal<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tdestinationSchema: TreeFieldStoredSchema,\n): PreparedContent {\n\tconst mapTree = flexTreeFromInsertable(data, schema);\n\n\tconst contentArray = mapTree === undefined ? [] : [mapTree];\n\tconst normalizedFieldSchema = normalizeFieldSchema(schema);\n\tconst fieldSchema = convertField(\n\t\tnormalizedFieldSchema as unknown as SimpleFieldSchema<SchemaType.Stored>,\n\t);\n\n\tconst field = createField(\n\t\tgetUnhydratedContext(normalizedFieldSchema).flexContext,\n\t\tfieldSchema.kind,\n\t\tdummyRoot,\n\t\tcontentArray,\n\t);\n\n\treturn validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, field);\n}\n\n/**\n * If hydrating, do a final validation against the schema and prepare the content for hydration.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n *\n * TODO: return nodes flex tree nodes to insert (might be newly hydrated) or reused unhydrated nodes when hydratedData is undefined.\n */\nfunction validateAndPrepare(\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tfieldSchema: TreeFieldStoredSchema,\n\tfield: UnhydratedFlexTreeField,\n): PreparedContent {\n\tconst cleanup = (): void => {\n\t\t// Discard the parent dummy field for the nodes before returning so they are unparented and can be inserted.\n\t\tfor (const child of field.children) {\n\t\t\tassert(child instanceof UnhydratedFlexTreeNode, \"TODO\");\n\t\t\tchild.adoptBy(undefined);\n\t\t}\n\t};\n\n\tif (hydratedData === undefined) {\n\t\treturn { toAttach: [...field.children], finalize: cleanup };\n\t} else {\n\t\t// Run `chunkForInsertion` before walking the tree in `isFieldInSchema`.\n\t\t// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),\n\t\t// they were already creating used the more specific context we have access to from `hydratedData`.\n\t\tconst chunk = chunkForInsertion(hydratedData, field);\n\t\t// TODO: AB#45723\n\t\t// Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.\n\t\t// We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).\n\t\t// Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.\n\t\tif (validateSchema === true) {\n\t\t\tisFieldInSchema(field, fieldSchema, schemaAndPolicy, throwOutOfSchema);\n\t\t}\n\n\t\tconst rootsLocations = hydratedData.checkout.editor.buildRoots(chunk.chunk);\n\t\t// console.log(`built nodes: ${JSON.stringify(rootsLocations)}`);\n\n\t\tconst toAttach =\n\t\t\thydratedData.detachedField === undefined\n\t\t\t\t? undefined\n\t\t\t\t: rootsLocations.map((f) => {\n\t\t\t\t\t\tassert(\n\t\t\t\t\t\t\thydratedData.detachedField !== undefined,\n\t\t\t\t\t\t\t\"detachedField should not stop being defined\",\n\t\t\t\t\t\t);\n\t\t\t\t\t\tconst rootField = hydratedData.detachedField(\n\t\t\t\t\t\t\tkeyAsDetachedField(f.field),\n\t\t\t\t\t\t\tFieldKinds.optional.identifier,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tassert(rootField.length === 1, \"Expected single root in detached field\");\n\t\t\t\t\t\treturn rootField.boxedAt(0) ?? fail(\"Expected root to be present\");\n\t\t\t\t\t});\n\n\t\treturn {\n\t\t\ttoAttach,\n\t\t\trootsLocations,\n\t\t\tfinalize: (attached: readonly FlexTreeNode[]) => {\n\t\t\t\t// do edits to move existing content into newly built tree and hydrate nodes as needed\n\t\t\t\tattachAndHydratedNodes([...attached], chunk.attaches);\n\t\t\t\tcleanup();\n\t\t\t},\n\t\t};\n\t}\n}\n\n/**\n * A field to insert, which can contain some attach operations for already hydrated content.\n */\ninterface ChunkedInsertion<TChunk = TreeChunk> {\n\treadonly chunk: TChunk;\n\treadonly attaches: readonly SubFieldAttach[];\n}\n\ntype SubFieldAttach = SubFieldAttachHydrated | SubFieldAttachUnhydrated;\n\n/**\n * A an unhydrated subtree is being attached to a hydrated context and it\n * contains content which need fixing up after the initial creation in the hydrated context.\n *\n */\ninterface SubFieldAttachUnhydrated {\n\treadonly type: \"unhydrated\";\n\treadonly index: number;\n\t/**\n\t * If provided a preexisting TreeNode which was unhydrated was attached.\n\t *\n\t * It will require hydration to associate the existing TreeNode with the new hydrated flex-tree node.\n\t */\n\treadonly toHydrate: TreeNode | undefined;\n\treadonly content: Map<FieldKey, readonly SubFieldAttach[]>;\n}\n\n/**\n * A preexisting TreeNode which was already hydrated was attached.\n *\n * It will require an attach to move its existing flex-tree node to the new location.\n */\ninterface SubFieldAttachHydrated {\n\treadonly type: \"hydrated\";\n\treadonly index: number;\n\treadonly content: HydratedFlexTreeNode;\n}\n\nfunction chunkForInsertion(\n\tcontext: FlexTreeHydratedContextMinimal,\n\tfield: UnhydratedFlexTreeField,\n): ChunkedInsertion {\n\tconst x = chunkFieldForInsertion(context, field);\n\tconst chunks = context.checkout.forest.chunkField(cursorForMapTreeField(x.chunk));\n\tconst chunk = combineChunks(chunks);\n\treturn {\n\t\tchunk,\n\t\tattaches: x.attaches,\n\t};\n}\n\nfunction chunkFieldForInsertion(\n\tcontext: FlexTreeHydratedContextMinimal,\n\tfield: UnhydratedFlexTreeField,\n): ChunkedInsertion<readonly MinimalMapTreeNodeView[]> {\n\tconst chunk: MinimalMapTreeNodeView[] = [];\n\tconst attaches: SubFieldAttach[] = [];\n\tfor (const [i, child] of field.children.entries()) {\n\t\tif (child.isHydrated()) {\n\t\t\t// TODO: error if there is a hydrated parent.\n\t\t\tattaches.push({\n\t\t\t\tindex: i,\n\t\t\t\tcontent: child,\n\t\t\t\ttype: \"hydrated\",\n\t\t\t});\n\t\t} else {\n\t\t\tassert(\n\t\t\t\tchild instanceof UnhydratedFlexTreeNode,\n\t\t\t\t\"Expected child to be an UnhydratedFlexTreeNode\",\n\t\t\t);\n\t\t\tconst fields: Map<FieldKey, readonly MinimalMapTreeNodeView[]> = new Map();\n\t\t\tconst childAttaches: Map<FieldKey, readonly SubFieldAttach[]> = new Map();\n\t\t\tfor (const [key, fieldInner] of child.allFieldsLazy) {\n\t\t\t\tfieldInner.fillPendingDefaults(context);\n\t\t\t\tif (fieldInner.length > 0) {\n\t\t\t\t\tconst inner = chunkFieldForInsertion(context, fieldInner);\n\t\t\t\t\tfields.set(key, inner.chunk);\n\t\t\t\t\tchildAttaches.set(key, inner.attaches);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// As an optimization, if there are no attach data, skip tracking it.\n\t\t\tif (childAttaches.size > 0 || child.treeNode !== undefined) {\n\t\t\t\tattaches.push({\n\t\t\t\t\tindex: i,\n\t\t\t\t\ttoHydrate: child.treeNode,\n\t\t\t\t\tcontent: childAttaches,\n\t\t\t\t\ttype: \"unhydrated\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tchunk.push({ type: child.type, value: child.value, fields });\n\t\t}\n\t}\n\treturn {\n\t\tchunk,\n\t\tattaches,\n\t};\n}\n\nfunction attachAndHydratedNodes(\n\tfield: FlexTreeField | FlexTreeNode[],\n\tattaches: readonly SubFieldAttach[],\n): void {\n\tfor (const attach of attaches) {\n\t\tif (attach.type === \"hydrated\") {\n\t\t\t// TODO: suppress events for these attaches?\n\n\t\t\tif (Array.isArray(field)) {\n\t\t\t\t// Move items after attach over by 1.\n\t\t\t\tfor (let index = field.length; index > attach.index; index--) {\n\t\t\t\t\tfield[index] = field[index - 1] ?? fail(\"No item at index\");\n\t\t\t\t}\n\t\t\t\tfield[attach.index] = attach.content;\n\t\t\t} else if (field.is(FieldKinds.sequence)) {\n\t\t\t\tfield.editor.insert(attach.index, [attach.content]);\n\t\t\t} else if (field.is(FieldKinds.optional)) {\n\t\t\t\tassert(field.length === 0, \"Expected empty field for hydrated attach\");\n\t\t\t\tfield.editor.set(attach.content, false);\n\t\t\t} else {\n\t\t\t\t// TODO: ensure a good user facing error for this case.\n\t\t\t\tfail(\"Invalid field kind for hydrated attach\");\n\t\t\t}\n\t\t} else {\n\t\t\tconst child =\n\t\t\t\t(Array.isArray(field) ? field[attach.index] : field.boxedAt(attach.index)) ??\n\t\t\t\tfail(\"No child at index\");\n\t\t\tif (attach.toHydrate !== undefined) {\n\t\t\t\tassert(child.isHydrated(), \"Expected child to be hydrated\");\n\t\t\t\tgetKernel(attach.toHydrate).hydrate(child);\n\t\t\t}\n\t\t\tfor (const [key, children] of attach.content) {\n\t\t\t\tconst childField = child.getBoxed(key);\n\t\t\t\tattachAndHydratedNodes(childField, children);\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/lib/simple-tree/unhydratedFlexTreeFromInsertable.d.ts

@@ -3,10 +3,11 @@
  * Licensed under the MIT License.
  */
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { type ImplicitFieldSchema } from "./fieldSchema.js";
+import type { FlexTreeNode } from "../feature-libraries/index.js";
+import type { ImplicitFieldSchema } from "./fieldSchema.js";
 import { type TreeNode, type TreeNodeSchema, type Unhydrated, UnhydratedFlexTreeNode } from "./core/index.js";
 /**
- * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.
+ * Transforms an input {@link TypedNode} tree to a {@link FlexTreeNode}.
  * @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.
@@ -31,11 +32,19 @@ import { type TreeNode, type TreeNodeSchema, type Unhydrated, UnhydratedFlexTree
  * 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 declare function flexTreeFromInsertable<TIn extends InsertableContent | undefined>(data: TIn, allowedTypes: ImplicitFieldSchema): TIn extends undefined ? undefined : FlexTreeNode;
+/**
+ * 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.
+ */
 export declare function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(data: TIn, allowedTypes: ImplicitFieldSchema): TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 /**
- * Copy content from `data` into a UnhydratedFlexTreeNode.
+ * Copy content from `data` into a UnhydratedFlexTreeNode or return an existing node if `data` is a TreeNode.
  */
-export declare function unhydratedFlexTreeFromInsertableNode(data: InsertableContent, allowedTypes: ReadonlySet<TreeNodeSchema>): UnhydratedFlexTreeNode;
+export declare function flexTreeFromInsertableNode(data: InsertableContent, allowedTypes: ReadonlySet<TreeNodeSchema>): FlexTreeNode;
 /**
  * Returns all types for which the data is schema-compatible.
  * @remarks This will respect the {@link contentSchemaSymbol} property on data to disambiguate types - if present, only that type will be returned.

package/lib/simple-tree/unhydratedFlexTreeFromInsertable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unhydratedFlexTreeFromInsertable.d.ts","sourceRoot":"","sources":["../../src/simple-tree/unhydratedFlexTreeFromInsertable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAMpE,OAAO,EAAmC,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAKN,KAAK,QAAQ,EACb,KAAK,cAAc,EAEnB,KAAK,UAAU,EACf,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EACzF,IAAI,EAAE,GAAG,EACT,YAAY,EAAE,mBAAmB,GAC/B,GAAG,SAAS,SAAS,GAAG,SAAS,GAAG,sBAAsB,CAiB5D;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CACnD,IAAI,EAAE,iBAAiB,EACvB,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,GACvC,sBAAsB,CA0BxB;AA2BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,EACzC,IAAI,EAAE,cAAc,GAClB,cAAc,EAAE,CA2BlB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACvB,YAAY,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GAEP,IAAI,GACJ,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,GAC9C,SAAS,iBAAiB,EAAE,GAC5B,oBAAoB,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,iBAAiB;CAC1C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC"}
+{"version":3,"file":"unhydratedFlexTreeFromInsertable.d.ts","sourceRoot":"","sources":["../../src/simple-tree/unhydratedFlexTreeFromInsertable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAMpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAKN,KAAK,QAAQ,EACb,KAAK,cAAc,EAEnB,KAAK,UAAU,EACf,sBAAsB,EACtB,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EAC/E,IAAI,EAAE,GAAG,EACT,YAAY,EAAE,mBAAmB,GAC/B,GAAG,SAAS,SAAS,GAAG,SAAS,GAAG,YAAY,CAiBlD;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EACzF,IAAI,EAAE,GAAG,EACT,YAAY,EAAE,mBAAmB,GAC/B,GAAG,SAAS,SAAS,GAAG,SAAS,GAAG,sBAAsB,CAO5D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,iBAAiB,EACvB,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,GACvC,YAAY,CAgCd;AA2BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,YAAY,EAAE,WAAW,CAAC,cAAc,CAAC,EACzC,IAAI,EAAE,cAAc,GAClB,cAAc,EAAE,CA2BlB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACvB,YAAY,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GAEP,IAAI,GACJ,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,GAC9C,SAAS,iBAAiB,EAAE,GAC5B,oBAAoB,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,iBAAiB;CAC1C,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC"}

package/lib/simple-tree/unhydratedFlexTreeFromInsertable.js

@@ -9,7 +9,7 @@ import { normalizeFieldSchema, FieldKind } from "./fieldSchema.js";
 import { CompatibilityLevel, getKernel, getTreeNodeSchemaPrivateData, isTreeNode, contentSchemaSymbol, UnhydratedFlexTreeNode, } from "./core/index.js";
 import { getUnhydratedContext } from "./createContext.js";
 /**
- * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.
+ * Transforms an input {@link TypedNode} tree to a {@link FlexTreeNode}.
  * @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.
@@ -34,7 +34,7 @@ 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 unhydratedFlexTreeFromInsertable(data, allowedTypes) {
+export function flexTreeFromInsertable(data, allowedTypes) {
     const normalizedFieldSchema = normalizeFieldSchema(allowedTypes);
     if (data === undefined) {
         // TODO: this code-path should support defaults
@@ -43,26 +43,43 @@ export function unhydratedFlexTreeFromInsertable(data, allowedTypes) {
         }
         return undefined;
     }
-    const flexTree = unhydratedFlexTreeFromInsertableNode(data, normalizedFieldSchema.allowedTypeSet);
+    const flexTree = flexTreeFromInsertableNode(data, normalizedFieldSchema.allowedTypeSet);
     return flexTree;
 }
 /**
- * Copy content from `data` into a 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.
+ */
+export function unhydratedFlexTreeFromInsertable(data, allowedTypes) {
+    const result = flexTreeFromInsertable(data, allowedTypes);
+    if (result === undefined) {
+        return undefined;
+    }
+    assert(result instanceof UnhydratedFlexTreeNode, "expected unhydrated node");
+    return result;
+}
+/**
+ * Copy content from `data` into a UnhydratedFlexTreeNode or return an existing node if `data` is a TreeNode.
  */
-export function unhydratedFlexTreeFromInsertableNode(data, allowedTypes) {
+export function flexTreeFromInsertableNode(data, allowedTypes) {
     if (isTreeNode(data)) {
         const kernel = getKernel(data);
-        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 {
+        const inner = kernel.getInnerNode();
+        if (inner.parentField.parent.parent === undefined) {
             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.");
+        }
     }
     const schema = getType(data, allowedTypes);
     const handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();

package/lib/simple-tree/unhydratedFlexTreeFromInsertable.js.map

@@ -1 +1 @@
-{"version":3,"file":"unhydratedFlexTreeFromInsertable.js","sourceRoot":"","sources":["../../src/simple-tree/unhydratedFlexTreeFromInsertable.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\n\nimport { filterIterable, hasSingle, oneFromIterable } from \"../util/index.js\";\n\nimport { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from \"./fieldSchema.js\";\nimport {\n\tCompatibilityLevel,\n\tgetKernel,\n\tgetTreeNodeSchemaPrivateData,\n\tisTreeNode,\n\ttype TreeNode,\n\ttype TreeNodeSchema,\n\tcontentSchemaSymbol,\n\ttype Unhydrated,\n\tUnhydratedFlexTreeNode,\n} from \"./core/index.js\";\nimport { getUnhydratedContext } from \"./createContext.js\";\n\n/**\n * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.\n * @param data - The input tree to be converted.\n * If the data is an unsupported value (e.g. NaN), a fallback value will be used when supported,\n * otherwise an error will be thrown.\n *\n * Fallbacks:\n *\n * * `NaN` =\\> `null`\n *\n * * `+/-∞` =\\> `null`\n *\n * * `-0` =\\> `+0`\n *\n * For fields with a default value, the field may be omitted.\n * If `context` is not provided, defaults which require a context will be left empty which can be out of schema.\n *\n * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.\n * @remarks\n * The resulting tree will be populated with any defaults from {@link FieldProvider}s in the schema.\n *\n * Often throws UsageErrors for invalid data, but may miss some cases.\n *\n * Output should comply with the provided view schema, but this is not explicitly validated:\n * validation against stored schema (to guard against document corruption) is done elsewhere.\n */\nexport function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tallowedTypes: ImplicitFieldSchema,\n): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {\n\tconst normalizedFieldSchema = normalizeFieldSchema(allowedTypes);\n\n\tif (data === undefined) {\n\t\t// TODO: this code-path should support defaults\n\t\tif (normalizedFieldSchema.kind !== FieldKind.Optional) {\n\t\t\tthrow new UsageError(\"Got undefined for non-optional field.\");\n\t\t}\n\t\treturn undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;\n\t}\n\n\tconst flexTree: UnhydratedFlexTreeNode = unhydratedFlexTreeFromInsertableNode(\n\t\tdata,\n\t\tnormalizedFieldSchema.allowedTypeSet,\n\t);\n\n\treturn flexTree as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;\n}\n\n/**\n * Copy content from `data` into a UnhydratedFlexTreeNode.\n */\nexport function unhydratedFlexTreeFromInsertableNode(\n\tdata: InsertableContent,\n\tallowedTypes: ReadonlySet<TreeNodeSchema>,\n): UnhydratedFlexTreeNode {\n\tif (isTreeNode(data)) {\n\t\tconst kernel = getKernel(data);\n\t\tconst inner = kernel.getInnerNodeIfUnhydrated();\n\t\tif (inner === undefined) {\n\t\t\t// The node is already hydrated, meaning that it already got inserted into the tree previously\n\t\t\tthrow new UsageError(\"A node may not be inserted into the tree more than once\");\n\t\t} else {\n\t\t\tif (!allowedTypes.has(kernel.schema)) {\n\t\t\t\tthrow new UsageError(\"Invalid schema for this context.\");\n\t\t\t}\n\t\t\treturn inner;\n\t\t}\n\t}\n\n\tconst schema = getType(data, allowedTypes);\n\tconst handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();\n\tconst result = handler.toFlexContent(data, allowedTypes);\n\n\t// Might not match schema due to fallbacks, see TODO on toFlexContent\n\t// TODO: fix TODO in `toFlexContent`, and remove this.\n\tconst finalSchema =\n\t\toneFromIterable(filterIterable(allowedTypes, (s) => s.identifier === result[0].type)) ??\n\t\tfail(0xc9d /* missing schema */);\n\n\treturn new UnhydratedFlexTreeNode(...result, getUnhydratedContext(finalSchema));\n}\n\nfunction getType(\n\tdata: FactoryContent,\n\tallowedTypes: ReadonlySet<TreeNodeSchema>,\n): TreeNodeSchema {\n\tconst possibleTypes = getPossibleTypes(allowedTypes, data);\n\tif (possibleTypes.length === 0) {\n\t\tthrow new UsageError(\n\t\t\t`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${JSON.stringify(\n\t\t\t\t[...allowedTypes].map((schema) => schema.identifier),\n\t\t\t)}.`,\n\t\t);\n\t}\n\tif (!hasSingle(possibleTypes)) {\n\t\tthrow new UsageError(\n\t\t\t`The provided data is compatible with more than one type allowed by the schema.\nThe set of possible types is ${JSON.stringify([\n\t\t\t\t...possibleTypes.map((schema) => schema.identifier),\n\t\t\t])}.\nExplicitly construct an unhydrated node of the desired type to disambiguate.\nFor class-based schema, this can be done by replacing an expression like \"{foo: 1}\" with \"new MySchema({foo: 1})\".`,\n\t\t);\n\t}\n\treturn possibleTypes[0];\n}\n\n/**\n * Returns all types for which the data is schema-compatible.\n * @remarks This will respect the {@link contentSchemaSymbol} property on data to disambiguate types - if present, only that type will be returned.\n */\nexport function getPossibleTypes(\n\tallowedTypes: ReadonlySet<TreeNodeSchema>,\n\tdata: FactoryContent,\n): TreeNodeSchema[] {\n\tassert(data !== undefined, 0x889 /* undefined cannot be used as FactoryContent. */);\n\n\tlet toCheck: Iterable<TreeNodeSchema>;\n\tif (typeof data === \"object\" && data !== null && contentSchemaSymbol in data) {\n\t\t// If the data has an explicit brand via contentSchemaSymbol, only check that type.\n\t\tconst type = data[contentSchemaSymbol];\n\t\ttoCheck = filterIterable(allowedTypes, (schema) => schema.identifier === type);\n\t} else {\n\t\ttoCheck = allowedTypes;\n\t}\n\n\t// Start at the lowest level of compat we would ever accept: this discards types which are less compatible.\n\tlet best = CompatibilityLevel.Low;\n\tconst possibleTypes: TreeNodeSchema[] = [];\n\tfor (const schema of toCheck) {\n\t\tconst handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();\n\t\tconst level = handler.shallowCompatibilityTest(data);\n\t\tif (level > best) {\n\t\t\tpossibleTypes.length = 0;\n\t\t\tbest = level;\n\t\t}\n\t\tif (best === level) {\n\t\t\tpossibleTypes.push(schema);\n\t\t}\n\t}\n\treturn possibleTypes;\n}\n\n/**\n * Content which can be used to build a node.\n * @remarks\n * Can contain unhydrated nodes, but can not be an unhydrated node at the root.\n * @system @alpha\n */\nexport type FactoryContent =\n\t| IFluidHandle\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| Iterable<readonly [string, InsertableContent]>\n\t| readonly InsertableContent[]\n\t| FactoryContentObject;\n\n/**\n * Record-like object which can be used to build some kinds of nodes.\n * @remarks\n * Can contain unhydrated nodes, but can not be an unhydrated node at the root.\n *\n * Supports object and map nodes.\n * @system @alpha\n */\nexport type FactoryContentObject = {\n\treadonly [P in string]?: InsertableContent;\n};\n\n/**\n * Content which can be inserted into a tree.\n * @system @alpha\n */\nexport type InsertableContent = Unhydrated<TreeNode> | FactoryContent;\n"]}
+{"version":3,"file":"unhydratedFlexTreeFromInsertable.js","sourceRoot":"","sources":["../../src/simple-tree/unhydratedFlexTreeFromInsertable.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\n\nimport { filterIterable, hasSingle, oneFromIterable } from \"../util/index.js\";\n\nimport type { FlexTreeNode } from \"../feature-libraries/index.js\";\n\nimport type { ImplicitFieldSchema } from \"./fieldSchema.js\";\nimport { normalizeFieldSchema, FieldKind } from \"./fieldSchema.js\";\nimport {\n\tCompatibilityLevel,\n\tgetKernel,\n\tgetTreeNodeSchemaPrivateData,\n\tisTreeNode,\n\ttype TreeNode,\n\ttype TreeNodeSchema,\n\tcontentSchemaSymbol,\n\ttype Unhydrated,\n\tUnhydratedFlexTreeNode,\n} from \"./core/index.js\";\nimport { getUnhydratedContext } from \"./createContext.js\";\n\n/**\n * Transforms an input {@link TypedNode} tree to a {@link FlexTreeNode}.\n * @param data - The input tree to be converted.\n * If the data is an unsupported value (e.g. NaN), a fallback value will be used when supported,\n * otherwise an error will be thrown.\n *\n * Fallbacks:\n *\n * * `NaN` =\\> `null`\n *\n * * `+/-∞` =\\> `null`\n *\n * * `-0` =\\> `+0`\n *\n * For fields with a default value, the field may be omitted.\n * If `context` is not provided, defaults which require a context will be left empty which can be out of schema.\n *\n * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.\n * @remarks\n * The resulting tree will be populated with any defaults from {@link FieldProvider}s in the schema.\n *\n * Often throws UsageErrors for invalid data, but may miss some cases.\n *\n * Output should comply with the provided view schema, but this is not explicitly validated:\n * validation against stored schema (to guard against document corruption) is done elsewhere.\n */\nexport function flexTreeFromInsertable<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tallowedTypes: ImplicitFieldSchema,\n): TIn extends undefined ? undefined : FlexTreeNode {\n\tconst normalizedFieldSchema = normalizeFieldSchema(allowedTypes);\n\n\tif (data === undefined) {\n\t\t// TODO: this code-path should support defaults\n\t\tif (normalizedFieldSchema.kind !== FieldKind.Optional) {\n\t\t\tthrow new UsageError(\"Got undefined for non-optional field.\");\n\t\t}\n\t\treturn undefined as TIn extends undefined ? undefined : FlexTreeNode;\n\t}\n\n\tconst flexTree: FlexTreeNode = flexTreeFromInsertableNode(\n\t\tdata,\n\t\tnormalizedFieldSchema.allowedTypeSet,\n\t);\n\n\treturn flexTree as TIn extends undefined ? undefined : FlexTreeNode;\n}\n\n/**\n * Wrapper around {@link flexTreeFromInsertable} which always returns an unhydrated nodes (or undefined).\n * @remarks\n * This does not deeply check content is unhydrated.\n *\n * Once hybrid content is better supported, this should likely be removed as a simplification.\n */\nexport function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tallowedTypes: ImplicitFieldSchema,\n): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {\n\tconst result = flexTreeFromInsertable(data, allowedTypes);\n\tif (result === undefined) {\n\t\treturn undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;\n\t}\n\tassert(result instanceof UnhydratedFlexTreeNode, \"expected unhydrated node\");\n\treturn result as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;\n}\n\n/**\n * Copy content from `data` into a UnhydratedFlexTreeNode or return an existing node if `data` is a TreeNode.\n */\nexport function flexTreeFromInsertableNode(\n\tdata: InsertableContent,\n\tallowedTypes: ReadonlySet<TreeNodeSchema>,\n): FlexTreeNode {\n\tif (isTreeNode(data)) {\n\t\tconst kernel = getKernel(data);\n\t\tconst inner = kernel.getInnerNode();\n\t\tif (inner.parentField.parent.parent === undefined) {\n\t\t\tif (!allowedTypes.has(kernel.schema)) {\n\t\t\t\tthrow new UsageError(\"Invalid schema for this context.\");\n\t\t\t}\n\n\t\t\tif (inner.isHydrated()) {\n\t\t\t\t// TODO: hook up event bubbling from hydrated to unhydrated tree.\n\t\t\t}\n\n\t\t\treturn inner;\n\t\t} else {\n\t\t\tthrow new UsageError(\n\t\t\t\t\"A node which already has a parent may not be used as part of a new tree.\",\n\t\t\t);\n\t\t}\n\t}\n\n\tconst schema = getType(data, allowedTypes);\n\tconst handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();\n\tconst result = handler.toFlexContent(data, allowedTypes);\n\n\t// Might not match schema due to fallbacks, see TODO on toFlexContent\n\t// TODO: fix TODO in `toFlexContent`, and remove this.\n\tconst finalSchema =\n\t\toneFromIterable(filterIterable(allowedTypes, (s) => s.identifier === result[0].type)) ??\n\t\tfail(0xc9d /* missing schema */);\n\n\treturn new UnhydratedFlexTreeNode(...result, getUnhydratedContext(finalSchema));\n}\n\nfunction getType(\n\tdata: FactoryContent,\n\tallowedTypes: ReadonlySet<TreeNodeSchema>,\n): TreeNodeSchema {\n\tconst possibleTypes = getPossibleTypes(allowedTypes, data);\n\tif (possibleTypes.length === 0) {\n\t\tthrow new UsageError(\n\t\t\t`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${JSON.stringify(\n\t\t\t\t[...allowedTypes].map((schema) => schema.identifier),\n\t\t\t)}.`,\n\t\t);\n\t}\n\tif (!hasSingle(possibleTypes)) {\n\t\tthrow new UsageError(\n\t\t\t`The provided data is compatible with more than one type allowed by the schema.\nThe set of possible types is ${JSON.stringify([\n\t\t\t\t...possibleTypes.map((schema) => schema.identifier),\n\t\t\t])}.\nExplicitly construct an unhydrated node of the desired type to disambiguate.\nFor class-based schema, this can be done by replacing an expression like \"{foo: 1}\" with \"new MySchema({foo: 1})\".`,\n\t\t);\n\t}\n\treturn possibleTypes[0];\n}\n\n/**\n * Returns all types for which the data is schema-compatible.\n * @remarks This will respect the {@link contentSchemaSymbol} property on data to disambiguate types - if present, only that type will be returned.\n */\nexport function getPossibleTypes(\n\tallowedTypes: ReadonlySet<TreeNodeSchema>,\n\tdata: FactoryContent,\n): TreeNodeSchema[] {\n\tassert(data !== undefined, 0x889 /* undefined cannot be used as FactoryContent. */);\n\n\tlet toCheck: Iterable<TreeNodeSchema>;\n\tif (typeof data === \"object\" && data !== null && contentSchemaSymbol in data) {\n\t\t// If the data has an explicit brand via contentSchemaSymbol, only check that type.\n\t\tconst type = data[contentSchemaSymbol];\n\t\ttoCheck = filterIterable(allowedTypes, (schema) => schema.identifier === type);\n\t} else {\n\t\ttoCheck = allowedTypes;\n\t}\n\n\t// Start at the lowest level of compat we would ever accept: this discards types which are less compatible.\n\tlet best = CompatibilityLevel.Low;\n\tconst possibleTypes: TreeNodeSchema[] = [];\n\tfor (const schema of toCheck) {\n\t\tconst handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();\n\t\tconst level = handler.shallowCompatibilityTest(data);\n\t\tif (level > best) {\n\t\t\tpossibleTypes.length = 0;\n\t\t\tbest = level;\n\t\t}\n\t\tif (best === level) {\n\t\t\tpossibleTypes.push(schema);\n\t\t}\n\t}\n\treturn possibleTypes;\n}\n\n/**\n * Content which can be used to build a node.\n * @remarks\n * Can contain unhydrated nodes, but can not be an unhydrated node at the root.\n * @system @alpha\n */\nexport type FactoryContent =\n\t| IFluidHandle\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| Iterable<readonly [string, InsertableContent]>\n\t| readonly InsertableContent[]\n\t| FactoryContentObject;\n\n/**\n * Record-like object which can be used to build some kinds of nodes.\n * @remarks\n * Can contain unhydrated nodes, but can not be an unhydrated node at the root.\n *\n * Supports object and map nodes.\n * @system @alpha\n */\nexport type FactoryContentObject = {\n\treadonly [P in string]?: InsertableContent;\n};\n\n/**\n * Content which can be inserted into a tree.\n * @system @alpha\n */\nexport type InsertableContent = Unhydrated<TreeNode> | FactoryContent;\n"]}

package/lib/text/index.d.ts

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { TextAsTree } from "./textDomain.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/text/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/text/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/text/index.js

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { TextAsTree } from "./textDomain.js";
+//# sourceMappingURL=index.js.map

package/lib/text/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/text/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { TextAsTree } from \"./textDomain.js\";\n"]}

package/lib/text/textDomain.d.ts

@@ -0,0 +1,138 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { TreeNode, WithType } from "../simple-tree/index.js";
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:
+ * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).
+ * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.
+ * - Character attributes (e.g. bold, italic, etc):
+ * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.
+ * - Inline objects (e.g. images, embedded components, etc):
+ * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.
+ * How character attributes apply to inline objects is an open question
+ * (there could be a kind of object which gets them, and one that doesn't for example).
+ * - Annotations (e.g. comments, suggestions, etc).
+ * Objects which can be associated with a range of characters but are not logically part of the text.
+ * These would need to have the logical range they apply to updated by edits.
+ * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).
+ * These get a lifetime tied to the text node, not any of the characters the annotation covers,
+ * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.
+ * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).
+ * - Anchors (e.g. positions in the text which survive edits).
+ * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.
+ *
+ * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.
+ *
+ * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.
+ * These include:
+ * - Optimized persisted format.
+ * - Optimized in memory representation (via chunked forest).
+ * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).
+ * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).
+ * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.
+ *
+ * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.
+ * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.
+ * There are quite a few ways invariants could break, including:
+ * - concurrent edits without proper constraints.
+ * - collaboration with clients using compatible schema with different constraints.
+ * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).
+ * - a user inserting/constructing/importing invalid content.
+ *
+ * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or
+ * annotations which reference out of bounds character ranges.
+ * Addressing these issues mainly falls into these categories:
+ * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).
+ * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.
+ * - Constraints on edits to prevent invalid content from being created by merges.
+ * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.
+ *
+ * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.
+ *
+ * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:
+ * - Insertable content format (taken by the constructor and import APIs).
+ * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).
+ * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).
+ * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.
+ * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.
+ * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.
+ *
+ * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,
+ * in addition to implementing them for text.
+ * @internal
+ */
+export declare namespace TextAsTree {
+    /**
+     * Statics for text nodes.
+     * @internal
+     */
+    interface Statics {
+        /**
+         * Construct a {@link TextAsTree.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.
+         * 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 TextAsTree.Statics.fromString} for construction.
+     * @see {@link TextAsTree.(Tree:type)} for schema.
+     * @internal
+     */
+    interface Members {
+        /**
+         * 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.
+         */
+        characters(): Iterable<string>;
+        /**
+         * Copy the content of this node into a string.
+         */
+        fullString(): string;
+        /**
+         * 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 TextAsTree.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.
+         */
+        insertAt(index: number, additionalCharacters: string): void;
+        /**
+         * Remove a range from a string based on character index.
+         * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.
+         */
+        removeRange(index: number, length: number): void;
+    }
+    /**
+     * Schema for a text node.
+     * @remarks
+     * See {@link TextAsTree.Members} for the API.
+     * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.
+     * @internal
+     */
+    const Tree: Statics & import("../simple-tree/index.js").TreeNodeSchema<"com.fluidframework.text.Text", import("../simple-tree/index.js").NodeKind, Members & TreeNode & WithType<"com.fluidframework.text.Text", import("../simple-tree/index.js").NodeKind, unknown>, never, false>;
+    type Tree = Members & TreeNode & WithType<"com.fluidframework.text.Text">;
+}
+//# sourceMappingURL=textDomain.d.ts.map

package/lib/text/textDomain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textDomain.d.ts","sourceRoot":"","sources":["../../src/text/textDomain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAkDlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,yBAAiB,UAAU,CAAC;IAC3B;;;OAGG;IACH,UAAiB,OAAO;QACvB;;;WAGG;QACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UAAiB,OAAO;QACvB;;;;WAIG;QACH,UAAU,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE/B;;WAEG;QACH,UAAU,IAAI,MAAM,CAAC;QAErB;;;;;;;;;;;;WAYG;QACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;QAE5D;;;WAGG;QACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACjD;IAED;;;;;;OAMG;IACI,MAAM,IAAI,0QAAmD,CAAC;IACrE,KAAY,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,8BAA8B,CAAC,CAAC;CACjF"}

package/lib/text/textDomain.js

@@ -0,0 +1,118 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { EmptyKey } from "../core/index.js";
+import { eraseSchemaDetails, SchemaFactory, SchemaFactoryAlpha, TreeArrayNode, } from "../simple-tree/index.js";
+const sf = new SchemaFactoryAlpha("com.fluidframework.text");
+class TextNode extends sf.object("Text", {
+    content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
+}) {
+    insertAt(index, additionalCharacters) {
+        this.content.insertAt(index, TreeArrayNode.spread(charactersFromString(additionalCharacters)));
+    }
+    removeRange(index, length) {
+        this.content.removeRange(index, length);
+    }
+    characters() {
+        return this.content[Symbol.iterator]();
+    }
+    fullString() {
+        return this.content.join("");
+    }
+    static fromString(value) {
+        // Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its 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: [...charactersFromString(value)] });
+    }
+}
+/**
+ * Interpret a string as an iterable of characters.
+ * @remarks
+ * This mostly exists to clearly document where the code is interpreting a string as characters,
+ * 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) {
+    // 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.
+    return value;
+}
+class StringArray extends sf.array("StringArray", SchemaFactory.string) {
+}
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:
+ * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).
+ * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.
+ * - Character attributes (e.g. bold, italic, etc):
+ * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.
+ * - Inline objects (e.g. images, embedded components, etc):
+ * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.
+ * How character attributes apply to inline objects is an open question
+ * (there could be a kind of object which gets them, and one that doesn't for example).
+ * - Annotations (e.g. comments, suggestions, etc).
+ * Objects which can be associated with a range of characters but are not logically part of the text.
+ * These would need to have the logical range they apply to updated by edits.
+ * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).
+ * These get a lifetime tied to the text node, not any of the characters the annotation covers,
+ * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.
+ * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).
+ * - Anchors (e.g. positions in the text which survive edits).
+ * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.
+ *
+ * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.
+ *
+ * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.
+ * These include:
+ * - Optimized persisted format.
+ * - Optimized in memory representation (via chunked forest).
+ * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).
+ * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).
+ * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.
+ *
+ * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.
+ * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.
+ * There are quite a few ways invariants could break, including:
+ * - concurrent edits without proper constraints.
+ * - collaboration with clients using compatible schema with different constraints.
+ * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).
+ * - a user inserting/constructing/importing invalid content.
+ *
+ * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or
+ * annotations which reference out of bounds character ranges.
+ * Addressing these issues mainly falls into these categories:
+ * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).
+ * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.
+ * - Constraints on edits to prevent invalid content from being created by merges.
+ * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.
+ *
+ * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.
+ *
+ * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:
+ * - Insertable content format (taken by the constructor and import APIs).
+ * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).
+ * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).
+ * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.
+ * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.
+ * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.
+ *
+ * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,
+ * in addition to implementing them for text.
+ * @internal
+ */
+export var TextAsTree;
+(function (TextAsTree) {
+    /**
+     * Schema for a text node.
+     * @remarks
+     * See {@link TextAsTree.Members} for the API.
+     * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.
+     * @internal
+     */
+    TextAsTree.Tree = eraseSchemaDetails()(TextNode);
+})(TextAsTree || (TextAsTree = {}));
+//# sourceMappingURL=textDomain.js.map

package/lib/text/textDomain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textDomain.js","sourceRoot":"","sources":["../../src/text/textDomain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACN,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,aAAa,GACb,MAAM,yBAAyB,CAAC;AAGjC,MAAM,EAAE,GAAG,IAAI,kBAAkB,CAAC,yBAAyB,CAAC,CAAC;AAE7D,MAAM,QACL,SAAQ,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE;IACzB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;CACvE,CAAC;IAGK,QAAQ,CAAC,KAAa,EAAE,oBAA4B;QAC1D,IAAI,CAAC,OAAO,CAAC,QAAQ,CACpB,KAAK,EACL,aAAa,CAAC,MAAM,CAAC,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAChE,CAAC;IACH,CAAC;IACM,WAAW,CAAC,KAAa,EAAE,MAAc;QAC/C,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IACM,UAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxC,CAAC;IACM,UAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAEM,MAAM,CAAC,UAAU,CAAC,KAAa;QACrC,mJAAmJ;QACnJ,qKAAqK;QACrK,0EAA0E;QAC1E,OAAO,IAAI,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;CACD;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,KAAa;IAC1C,0GAA0G;IAC1G,iKAAiK;IACjK,0CAA0C;IAC1C,OAAO,KAAK,CAAC;AACd,CAAC;AAED,MAAM,WAAY,SAAQ,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC;CAAG;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,KAAW,UAAU,CA0E1B;AA1ED,WAAiB,UAAU;IAiE1B;;;;;;OAMG;IACU,eAAI,GAAG,kBAAkB,EAAoB,CAAC,QAAQ,CAAC,CAAC;AAEtE,CAAC,EA1EgB,UAAU,KAAV,UAAU,QA0E1B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { EmptyKey } from \"../core/index.js\";\nimport {\n\teraseSchemaDetails,\n\tSchemaFactory,\n\tSchemaFactoryAlpha,\n\tTreeArrayNode,\n} from \"../simple-tree/index.js\";\nimport type { TreeNode, WithType } from \"../simple-tree/index.js\";\n\nconst sf = new SchemaFactoryAlpha(\"com.fluidframework.text\");\n\nclass TextNode\n\textends sf.object(\"Text\", {\n\t\tcontent: SchemaFactory.required([() => StringArray], { key: EmptyKey }),\n\t})\n\timplements TextAsTree.Members\n{\n\tpublic insertAt(index: number, additionalCharacters: string): void {\n\t\tthis.content.insertAt(\n\t\t\tindex,\n\t\t\tTreeArrayNode.spread(charactersFromString(additionalCharacters)),\n\t\t);\n\t}\n\tpublic removeRange(index: number, length: number): void {\n\t\tthis.content.removeRange(index, length);\n\t}\n\tpublic characters(): Iterable<string> {\n\t\treturn this.content[Symbol.iterator]();\n\t}\n\tpublic fullString(): string {\n\t\treturn this.content.join(\"\");\n\t}\n\n\tpublic static fromString(value: string): TextNode {\n\t\t// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its not necessary here,\n\t\t// 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.\n\t\t// Thus the array construction here is necessary to avoid a runtime error.\n\t\treturn new TextNode({ content: [...charactersFromString(value)] });\n\t}\n}\n\n/**\n * Interpret a string as an iterable of characters.\n * @remarks\n * This mostly exists to clearly document where the code is interpreting a string as characters,\n * and provide a centralized place where validation could be added in the future if desired.\n * Additionally using this function consistently will make any refactors to support alternative character boundaries easier.\n */\nfunction charactersFromString(value: string): Iterable<string> {\n\t// Uses the string as an iterable of characters, so utf-16 surrogate pairs get grouped together correctly.\n\t// Might be nice to call isWellFormed or toWellFormed here (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toWellFormed)\n\t// But those are not widely supported yet.\n\treturn value;\n}\n\nclass StringArray extends sf.array(\"StringArray\", SchemaFactory.string) {}\n\n/**\n * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.\n * @privateRemarks\n * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:\n * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).\n * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.\n * - Character attributes (e.g. bold, italic, etc):\n * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.\n * - Inline objects (e.g. images, embedded components, etc):\n * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.\n * How character attributes apply to inline objects is an open question\n * (there could be a kind of object which gets them, and one that doesn't for example).\n * - Annotations (e.g. comments, suggestions, etc).\n * Objects which can be associated with a range of characters but are not logically part of the text.\n * These would need to have the logical range they apply to updated by edits.\n * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).\n * These get a lifetime tied to the text node, not any of the characters the annotation covers,\n * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.\n * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).\n * - Anchors (e.g. positions in the text which survive edits).\n * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.\n *\n * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.\n *\n * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.\n * These include:\n * - Optimized persisted format.\n * - Optimized in memory representation (via chunked forest).\n * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).\n * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).\n * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.\n *\n * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.\n * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.\n * There are quite a few ways invariants could break, including:\n * - concurrent edits without proper constraints.\n * - collaboration with clients using compatible schema with different constraints.\n * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).\n * - a user inserting/constructing/importing invalid content.\n *\n * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or\n * annotations which reference out of bounds character ranges.\n * Addressing these issues mainly falls into these categories:\n * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).\n * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.\n * - Constraints on edits to prevent invalid content from being created by merges.\n * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.\n *\n * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.\n *\n * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:\n * - Insertable content format (taken by the constructor and import APIs).\n * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).\n * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).\n * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.\n * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.\n * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.\n *\n * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,\n * in addition to implementing them for text.\n * @internal\n */\nexport namespace TextAsTree {\n\t/**\n\t * Statics for text nodes.\n\t * @internal\n\t */\n\texport interface Statics {\n\t\t/**\n\t\t * Construct a {@link TextAsTree.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.\n\t\t * This combines pairs of utf-16 surrogate code units into single characters as appropriate.\n\t\t */\n\t\tfromString(value: string): Tree;\n\t}\n\n\t/**\n\t * Interface for a text node.\n\t * @remarks\n\t * The string is broken up into substrings which are referred to as 'characters'.\n\t * Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit.\n\t * This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings,\n\t * and avoids the issue where indexing a string and iterating it segment the string differently.\n\t * This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do):\n\t * applications will likely want to include higher level segmentation logic\n\t * which might differ between operations like delete\n\t * (which often operates on something in between unicode code points and grapheme clusters)\n\t * and navigation/selection (which typically uses grapheme clusters).\n\t *\n\t * @see {@link TextAsTree.Statics.fromString} for construction.\n\t * @see {@link TextAsTree.(Tree:type)} for schema.\n\t * @internal\n\t */\n\texport interface Members {\n\t\t/**\n\t\t * Gets an iterable over the characters currently in the text.\n\t\t * @remarks\n\t\t * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.\n\t\t */\n\t\tcharacters(): Iterable<string>;\n\n\t\t/**\n\t\t * Copy the content of this node into a string.\n\t\t */\n\t\tfullString(): string;\n\n\t\t/**\n\t\t * Insert a range of characters into the string based on character index.\n\t\t * @remarks\n\t\t * See {@link (TreeArrayNode:interface).insertAt} for more details on the behavior.\n\t\t * See {@link TextAsTree.Statics.fromString} for how the `additionalCharacters` string is broken into characters.\n\t\t * @privateRemarks\n\t\t * If we provide ways to customize character boundaries, that could be handled here by taking in an Iterable<string> instead of a string.\n\t\t * Doing this currently would enable insertion of text with different character boundaries than the existing text,\n\t\t * which would violate the currently documented character boundary invariants.\n\t\t *\n\t\t * Another option would be to take an approach like Table,\n\t\t * where the user of the API uses a factory function to generate the schema, and can inject custom logic, like a string character iterator.\n\t\t */\n\t\tinsertAt(index: number, additionalCharacters: string): void;\n\n\t\t/**\n\t\t * Remove a range from a string based on character index.\n\t\t * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.\n\t\t */\n\t\tremoveRange(index: number, length: number): void;\n\t}\n\n\t/**\n\t * Schema for a text node.\n\t * @remarks\n\t * See {@link TextAsTree.Members} for the API.\n\t * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.\n\t * @internal\n\t */\n\texport const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);\n\texport type Tree = Members & TreeNode & WithType<\"com.fluidframework.text.Text\">;\n}\n"]}