@fluidframework/tree 2.4.0 → 2.5.0-302463

package/src/simple-tree/arrayNode.ts

@@ -18,6 +18,7 @@ import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type TreeLeafValue,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
@@ -34,6 +35,7 @@ import {
 	type TreeNodeSchemaBoth,
 	getSimpleNodeSchemaFromInnerNode,
 	getOrCreateInnerNode,
+	type TreeNodeSchemaClass,
 } from "./core/index.js";
 import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
 import { fail } from "../util/index.js";
@@ -45,6 +47,19 @@ import {
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
 
+/**
+ * A covariant base type for {@link (TreeArrayNode:interface)}.
+ *
+ * This provides the readonly subset of TreeArrayNode functionality, and is used as the source interface for moves since that needs to be covariant.
+ * @privateRemarks
+ * Ideally this would just include `TreeNode, WithType<string, NodeKind.Array>` in the extends list but https://github.com/microsoft/TypeScript/issues/16936 prevents that from compiling.
+ * As a workaround around for this TypeScript limitation, the conflicting type intersection is wrapped in `Awaited` (which has no effect on the type in this case) which allows it to compile.
+ * @system @sealed @public
+ */
+export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue>
+	extends ReadonlyArray<T>,
+		Awaited<TreeNode & WithType<string, NodeKind.Array>> {}
+
 /**
  * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
  *
@@ -53,9 +68,8 @@ import { getUnhydratedContext } from "./createContext.js";
  *
  * @system @sealed @public
  */
-export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>
-	extends ReadonlyArray<T>,
-		TreeNode {
+export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom = ReadonlyArrayNode>
+	extends ReadonlyArrayNode<T> {
 	/**
 	 * Inserts new item(s) at a specified location.
 	 * @param index - The index at which to insert `value`.
@@ -366,8 +380,7 @@ export interface TreeArrayNode<
 	TAllowedTypes extends ImplicitAllowedTypes = ImplicitAllowedTypes,
 > extends TreeArrayNodeBase<
 		TreeNodeFromImplicitAllowedTypes<TAllowedTypes>,
-		InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>,
-		TreeArrayNode
+		InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
 	> {}
 
 /**
@@ -417,9 +430,7 @@ export class IterableTreeArrayContent<T> implements Iterable<T> {
 /**
  * Given a array node proxy, returns its underlying LazySequence field.
  */
-function getSequenceField<TSimpleType extends ImplicitAllowedTypes>(
-	arrayNode: TreeArrayNode<TSimpleType>,
-): FlexTreeSequenceField {
+function getSequenceField(arrayNode: ReadonlyArrayNode): FlexTreeSequenceField {
 	return getOrCreateInnerNode(arrayNode).getBoxed(EmptyKey) as FlexTreeSequenceField;
 }
 
@@ -799,6 +810,11 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	protected abstract get simpleSchema(): T;
 	protected abstract get allowedTypes(): ReadonlySet<TreeNodeSchema>;
 
+	public abstract override get [typeSchemaSymbol](): TreeNodeSchemaClass<
+		string,
+		NodeKind.Array
+	>;
+
 	public constructor(
 		input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
 	) {
@@ -901,13 +917,13 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		}
 		field.editor.remove(removeStart, removeEnd - removeStart);
 	}
-	public moveToStart(sourceIndex: number, source?: TreeArrayNode): void {
+	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
 		validateIndex(sourceIndex, sourceField, "moveToStart");
 		this.moveRangeToIndex(0, sourceIndex, sourceIndex + 1, source);
 	}
-	public moveToEnd(sourceIndex: number, source?: TreeArrayNode): void {
+	public moveToEnd(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
 		validateIndex(sourceIndex, sourceField, "moveToEnd");
@@ -916,7 +932,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public moveToIndex(
 		destinationGap: number,
 		sourceIndex: number,
-		source?: TreeArrayNode,
+		source?: ReadonlyArrayNode,
 	): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
@@ -928,7 +944,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public moveRangeToStart(
 		sourceStart: number,
 		sourceEnd: number,
-		source?: TreeArrayNode,
+		source?: ReadonlyArrayNode,
 	): void {
 		validateIndexRange(
 			sourceStart,
@@ -938,7 +954,11 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		);
 		this.moveRangeToIndex(0, sourceStart, sourceEnd, source);
 	}
-	public moveRangeToEnd(sourceStart: number, sourceEnd: number, source?: TreeArrayNode): void {
+	public moveRangeToEnd(
+		sourceStart: number,
+		sourceEnd: number,
+		source?: ReadonlyArrayNode,
+	): void {
 		validateIndexRange(
 			sourceStart,
 			sourceEnd,
@@ -951,7 +971,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		destinationGap: number,
 		sourceStart: number,
 		sourceEnd: number,
-		source?: TreeArrayNode,
+		source?: ReadonlyArrayNode,
 	): void {
 		const destinationField = getSequenceField(this);
 		const destinationSchema = this.allowedTypes;

package/src/simple-tree/core/treeNodeSchema.ts

@@ -3,10 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
+import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 
 /**
- * Schema for a tree node.
+ * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
+ *
  * @typeParam Name - The full (including scope) name/identifier for the schema.
  * @typeParam Kind - Which kind of node this schema is for.
  * @typeParam TNode - API for nodes that use this schema.
@@ -14,12 +16,14 @@ import type { InternalTreeNode, Unhydrated } from "./types.js";
  * @typeParam Info - Data used when defining this schema.
  * @remarks
  * Captures the schema both as runtime data and compile time type information.
+ * Use {@link SchemaFactory} to define schema.
+ * Use `Tree.schema(value)` to lookup the schema for a {@link TreeNode} or {@link TreeLeafValue}.
  * @sealed @public
  */
 export type TreeNodeSchema<
 	Name extends string = string,
 	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
+	TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	TBuild = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
@@ -38,7 +42,7 @@ export type TreeNodeSchema<
 export interface TreeNodeSchemaNonClass<
 	out Name extends string = string,
 	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
+	out TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	in TInsertable = never,
 	out ImplicitlyConstructable extends boolean = boolean,
 	out Info = unknown,
@@ -94,7 +98,8 @@ export interface TreeNodeSchemaNonClass<
 export interface TreeNodeSchemaClass<
 	out Name extends string = string,
 	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
+	// TODO: maybe this can be more specific (exclude leaves)
+	out TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	in TInsertable = never,
 	out ImplicitlyConstructable extends boolean = boolean,
 	out Info = unknown,
@@ -115,7 +120,7 @@ export interface TreeNodeSchemaClass<
 export type TreeNodeSchemaBoth<
 	Name extends string = string,
 	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
+	TNode extends TreeNode = TreeNode,
 	TInsertable = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,

package/src/simple-tree/core/withType.ts

@@ -3,7 +3,9 @@
  * Licensed under the MIT License.
  */
 
+import type { TreeLeafValue } from "../schemaTypes.js";
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+import type { TreeNode } from "./types.js";
 
 /**
  * The type of a {@link TreeNode}.
@@ -87,5 +89,12 @@ export interface WithType<
 	/**
 	 * Type symbol, marking a type in a way to increase type safety via strong type checking.
 	 */
-	get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, unknown, never, boolean, TInfo>;
+	get [typeSchemaSymbol](): TreeNodeSchemaClass<
+		TName,
+		TKind,
+		TreeNode | TreeLeafValue,
+		never,
+		boolean,
+		TInfo
+	>;
 }

package/src/simple-tree/index.ts

@@ -40,7 +40,6 @@ export {
 	adaptEnum,
 	enumFromStrings,
 	singletonSchema,
-	typedObjectValues,
 	test_RecursiveObject,
 	test_RecursiveObject_base,
 	test_RecursiveObjectPojoMode,
@@ -92,6 +91,12 @@ export {
 	type NodeBuilderDataUnsafe,
 	type NodeFromSchemaUnsafe,
 	type ReadonlyMapInlined,
+	type TreeNodeSchemaClassUnsafe,
+	type TreeNodeSchemaUnsafe,
+	type AllowedTypesUnsafe,
+	type TreeNodeSchemaNonClassUnsafe,
+	type InsertableTreeNodeFromAllowedTypesUnsafe,
+	type TreeViewAlpha,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -113,6 +118,12 @@ export {
 	normalizeFieldSchema,
 	type ApplyKind,
 	type FieldSchemaMetadata,
+	type InsertableField,
+	type Insertable,
+	type UnsafeUnknownSchema,
+	type ApplyKindInput,
+	type InsertableTreeNodeFromAllowedTypes,
+	type Input,
 } from "./schemaTypes.js";
 export {
 	getTreeNodeForField,
@@ -122,6 +133,7 @@ export {
 	TreeArrayNode,
 	IterableTreeArrayContent,
 	type TreeArrayNodeBase,
+	type ReadonlyArrayNode,
 } from "./arrayNode.js";
 export {
 	type FieldHasDefault,
@@ -131,7 +143,12 @@ export {
 	setField,
 } from "./objectNode.js";
 export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
-export { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
+export {
+	mapTreeFromNodeData,
+	type InsertableContent,
+	type FactoryContent,
+	type FactoryContentObject,
+} from "./toMapTree.js";
 export { toStoredSchema, getStoredSchema } from "./toFlexSchema.js";
 export {
 	numberSchema,

package/src/simple-tree/mapNode.ts

@@ -128,7 +128,10 @@ export interface TreeMapNode<T extends ImplicitAllowedTypes = ImplicitAllowedTyp
 	): void;
 }
 
-const handler: ProxyHandler<TreeMapNode> = {
+// TreeMapNode is invariant over schema type, so for this handler to work with all schema, the only possible type for the schema is `any`.
+// This is not ideal, but no alternatives are possible.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const handler: ProxyHandler<TreeMapNode<any>> = {
 	getPrototypeOf: () => {
 		return Map.prototype;
 	},
@@ -177,7 +180,7 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		const node = this.innerNode;
 		return node.keys();
 	}
-	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): TreeMapNode {
+	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): this {
 		const kernel = getKernel(this);
 		const node = this.innerNode;
 		const mapTree = mapTreeFromNodeData(
@@ -244,7 +247,7 @@ export function mapSchema<
 			flexNode: FlexTreeNode,
 		): TreeNodeValid<T2> {
 			if (useMapPrototype) {
-				return new Proxy<Schema>(instance as Schema, handler);
+				return new Proxy<Schema>(instance as Schema, handler as ProxyHandler<Schema>);
 			}
 			return instance;
 		}

package/src/simple-tree/objectNode.ts

@@ -98,6 +98,8 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = T extends FieldSche
  *
  * 3. Union of 1 and 2.
  *
+ * @see {@link Input}
+ *
  * @privateRemarks TODO: consider separating these cases into different types.
  *
  * @system @public
@@ -107,13 +109,13 @@ export type InsertableObjectFromSchemaRecord<
 > = FlattenKeys<
 	{
 		readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
-			T[Property] & string
+			T[Property & string]
 		>;
 	} & {
 		// Field does not have a known default, make it required:
-		readonly [Property in keyof T as FieldHasDefault<T[Property] & string> extends false
+		readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
 			? Property
-			: never]: InsertableTreeFieldFromImplicitField<T[Property] & string>;
+			: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
 	}
 >;
 

package/src/simple-tree/schemaTypes.ts

@@ -8,12 +8,18 @@ import { Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { NodeKeyManager } from "../feature-libraries/index.js";
-import { type MakeNominal, brand, isReadonlyArray } from "../util/index.js";
+import {
+	type MakeNominal,
+	brand,
+	isReadonlyArray,
+	type UnionToIntersection,
+} from "../util/index.js";
 import type {
 	Unhydrated,
 	NodeKind,
 	TreeNodeSchema,
 	TreeNodeSchemaClass,
+	TreeNode,
 } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./toMapTree.js";
@@ -25,7 +31,7 @@ import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
 export function isTreeNodeSchemaClass<
 	Name extends string,
 	Kind extends NodeKind,
-	TNode,
+	TNode extends TreeNode | TreeLeafValue,
 	TBuild,
 	ImplicitlyConstructable extends boolean,
 	Info,
@@ -39,8 +45,16 @@ export function isTreeNodeSchemaClass<
  * Types for use in fields.
  * @remarks
  * Type constraint used in schema declaration APIs.
+ *
+ * The order of types in the array is not significant.
+ * Additionally, it is legal for users of this type to have the runtime and compile time order of items within this array not match.
+ * Therefor to ensure type safety, these arrays should not be indexed, and instead just be iterated.
+ *
+ * Ideally this restriction would be modeled in the type itself, but it is not ergonomic to do so as there is no easy (when compared to arrays)
+ * way to declare and manipulate unordered sets of types in TypeScript.
+ *
  * Not intended for direct use outside of package.
- * @public
+ * @system @public
  */
 export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 
@@ -381,39 +395,122 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;
 
 /**
- * Converts ImplicitFieldSchema to the corresponding tree node's field type.
+ * Converts an `ImplicitFieldSchema` to a property type suitable for reading a field with this that schema.
+ *
+ * @typeparam TSchema - When non-exact schema are provided this errors on the side of returning too general of a type (a conservative union of all possibilities).
+ * This is ideal for "output APIs" - i.e. it converts the schema type to the runtime type that a user will _read_ from the tree.
+ * Examples of such "non-exact" schema include `ImplicitFieldSchema`, `ImplicitAllowedTypes`, and  TypeScript unions of schema types.
  * @public
  */
 export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> =
 	TSchema extends FieldSchema<infer Kind, infer Types>
-		? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind, false>
+		? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind>
 		: TSchema extends ImplicitAllowedTypes
 			? TreeNodeFromImplicitAllowedTypes<TSchema>
-			: unknown;
+			: TreeNode | TreeLeafValue | undefined;
 
 /**
  * Type of content that can be inserted into the tree for a field of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchemaInput - Schema to process.
+ * @typeparam TSchema - Do not specify: default value used as implementation detail.
  * @public
  */
 export type InsertableTreeFieldFromImplicitField<
-	TSchema extends ImplicitFieldSchema = FieldSchema,
-> = TSchema extends FieldSchema<infer Kind, infer Types>
-	? ApplyKind<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>
-	: TSchema extends ImplicitAllowedTypes
+	TSchemaInput extends ImplicitFieldSchema,
+	TSchema = UnionToIntersection<TSchemaInput>,
+> = [TSchema] extends [FieldSchema<infer Kind, infer Types>]
+	? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>
+	: [TSchema] extends [ImplicitAllowedTypes]
 		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
-		: unknown;
+		: never;
+
+/**
+ * {@inheritdoc (UnsafeUnknownSchema:type)}
+ * @alpha
+ */
+export const UnsafeUnknownSchema: unique symbol = Symbol("UnsafeUnknownSchema");
+
+/**
+ * A special type which can be provided to some APIs as the schema type parameter when schema cannot easily be provided at compile time and an unsafe (instead of disabled) editing API is desired.
+ * @remarks
+ * When used, this means the TypeScript typing should err on the side of completeness (allow all inputs that could be valid).
+ * This introduces the risk that out-of-schema data could be allowed at compile time, and only error at runtime.
+ *
+ * @privateRemarks
+ * This only applies to APIs which input data which is expected to be in schema, since APIs outputting have easy mechanisms to do so in a type safe way even when the schema is unknown.
+ * In most cases that amounts to returning `TreeNode | TreeLeafValue`.
+ *
+ * This can be contrasted with the default behavior of TypeScript, which is to require the intersection of the possible types for input APIs,
+ * which for unknown schema defining input trees results in the `never` type.
+ *
+ * Any APIs which use this must produce UsageErrors when out of schema data is encountered, and never produce unrecoverable errors,
+ * or silently accept invalid data.
+ * This is currently only type exported from the package: the symbol is just used as a way to get a named type.
+ * @alpha
+ */
+export type UnsafeUnknownSchema = typeof UnsafeUnknownSchema;
+
+/**
+ * Content which could be inserted into a tree.
+ *
+ * @see {@link Input}
+ * @remarks
+ * Extended version of {@link InsertableTreeNodeFromImplicitAllowedTypes} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * @alpha
+ */
+export type Insertable<TSchema extends ImplicitAllowedTypes | UnsafeUnknownSchema> =
+	TSchema extends ImplicitAllowedTypes
+		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
+		: InsertableContent;
+
+/**
+ * Content which could be inserted into a field within a tree.
+ *
+ * @see {@link Input}
+ * @remarks
+ * Extended version of {@link InsertableTreeFieldFromImplicitField} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * @alpha
+ */
+export type InsertableField<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> = [
+	TSchema,
+] extends [ImplicitFieldSchema]
+	? InsertableTreeFieldFromImplicitField<TSchema>
+	: [TSchema] extends [UnsafeUnknownSchema]
+		? InsertableContent | undefined
+		: never;
 
 /**
  * Suitable for output.
  * For input must error on side of excluding undefined instead.
  * @system @public
  */
-export type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> = {
+export type ApplyKind<T, Kind extends FieldKind> = {
 	[FieldKind.Required]: T;
 	[FieldKind.Optional]: T | undefined;
-	[FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
+	[FieldKind.Identifier]: T;
 }[Kind];
 
+/**
+ * Suitable for input.
+ *
+ * @see {@link Input}
+ * @system @public
+ */
+export type ApplyKindInput<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> = [
+	Kind,
+] extends [FieldKind.Required]
+	? T
+	: [Kind] extends [FieldKind.Optional]
+		? T | undefined
+		: [Kind] extends [FieldKind.Identifier]
+			? DefaultsAreOptional extends true
+				? T | undefined
+				: T
+			: never;
+
 /**
  * Type of tree node for a field of the given schema.
  * @public
@@ -426,16 +523,91 @@ export type TreeNodeFromImplicitAllowedTypes<
 		? NodeFromSchema<FlexListToUnion<TSchema>>
 		: unknown;
 
+/**
+ * This type exists only to be linked from documentation to provide a single linkable place to document some details of
+ * "Input" types and how they handle schema.
+ *
+ * When a schema is used to describe data which is an input into an API, the API is [contravariant](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)) over the schema.
+ * (See also, [TypeScript Variance Annotations](https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations)).
+ *
+ * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.
+ *
+ * Consider a field with schema type of `A | B` (where A and B are types of schema).
+ *
+ * - Reading the field behaves covariantly so {@link NodeFromSchema} of `<A | B>` is the same as `NodeFromSchema<A> | NodeFromSchema<B>`, indicating that either type of node can be read from the field.
+ * - Writing to the field behaves contravariantly. Since it is unknown if the node actually has a schema `A` or a schema `B`, the only legal values (known to be in schema regardless of which schema the underlying node has) are values which are legal for both `A & B`.
+ *
+ * Note that this is distinct from the case where the schema is `[A, B]`.
+ * In this case it is known that the field allows both A and B (the field can be set to an A or a B value).
+ * When `A | B` is used, the field might allow
+ * A but not B (so assigning a B value would be out of schema),
+ * B but not A (so assigning an A value would be out of schema)
+ * or both A and B.
+ *
+ * This gets more extreme when given completely unspecified schema.
+ * For example if a field is just provided {@link ImplicitFieldSchema}, nothing is known about the content of the field.
+ * This means that reading the field (via {@link TreeFieldFromImplicitField}) can give any valid tree field content,
+ * but there are no safe values which could be written to the field (since it is unknown what values would be out of schema) so {@link InsertableTreeFieldFromImplicitField} gives `never`.
+ *
+ * To implement this variance correctly, the computation of types for input and output have to use separate utilities
+ * which take very different approaches when encountering non-exact schema like unions or `ImplicitFieldSchema`.
+ * The utilities which behave contravariantly (as required to handle input correctly) link this documentation to indicate that this is how they behave.
+ *
+ * In addition to behaving contravariantly, these input type computation utilities often have further limitations.
+ * This is due to TypeScript making it difficult to implement this contravariance exactly.
+ * When faced with these implementation limitations these contravariant type computation utilities error on the side of producing overly strict requirements.
+ * For example in the above case of `A | B`, the utilities might compute an allowed insertable type as `never` even if there happens to be a common value accepted by both `A` and `B`.
+ * Future versions of the API can relax these requirements as the type computations are made more accurate.
+ *
+ * For a more concrete example: if {@link InsertableTreeFieldFromImplicitField} produced `never` for a schema `A | OptionalField<A>`,
+ * a future version could instead return a more flexible but still safe type, like `A`.
+ *
+ * More generally: try to avoid providing non-exact schema, especially for the fields of other schema.
+ * While these APIs attempt to handle such cases correctly, there are limitations and known bugs in this handling.
+ * Code using non-exact schema is much more likely to have its compilation break due to updates of this package or even TypeScript,
+ * and thus compilation breaks due to edge cases of non-exact schema handling, especially with recursive schema, are not considered breaking changes.
+ * This may change as the API become more stable.
+ *
+ * @privateRemarks
+ * There likely is a better way to share this documentation, but none was found at the time of writing.
+ *
+ * TODO: Once {@link InsertableField} is public, consider using it in the examples above.
+ * @system @public
+ */
+export type Input<T extends never> = T;
+
 /**
  * Type of content that can be inserted into the tree for a node of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchema - Schema to process.
+ *
+ * @privateRemarks
+ * This is a bit overly conservative, since cases like `A | [A]` give never and could give `A`.
  * @public
  */
-export type InsertableTreeNodeFromImplicitAllowedTypes<
-	TSchema extends ImplicitAllowedTypes = TreeNodeSchema,
-> = TSchema extends TreeNodeSchema
-	? InsertableTypedNode<TSchema>
-	: TSchema extends AllowedTypes
-		? InsertableTypedNode<FlexListToUnion<TSchema>>
+export type InsertableTreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedTypes> =
+	[TSchema] extends [TreeNodeSchema]
+		? InsertableTypedNode<TSchema>
+		: [TSchema] extends [AllowedTypes]
+			? InsertableTreeNodeFromAllowedTypes<TSchema>
+			: never;
+
+/**
+ * Type of content that can be inserted into the tree for a node of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TList - AllowedTypes to process
+ * @system @public
+ */
+export type InsertableTreeNodeFromAllowedTypes<TList extends AllowedTypes> =
+	TList extends readonly [
+		LazyItem<infer TSchema extends TreeNodeSchema>,
+		...infer Rest extends AllowedTypes,
+	]
+		? InsertableTypedNode<TSchema> | InsertableTreeNodeFromAllowedTypes<Rest>
 		: never;
 
 /**
@@ -453,11 +625,31 @@ export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 /**
  * Data which can be used as a node to be inserted.
  * Either an unhydrated node, or content to build a new node.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchemaInput - Schema to process.
+ * @typeparam T - Do not specify: default value used as implementation detail.
+ * @privateRemarks
+ * This can't really be fully correct, since TreeNodeSchema's TNode is generally use covariantly but this code uses it contravariantly.
+ * That makes this TreeNodeSchema actually invariant with respect to TNode, but doing that would break all `extends TreeNodeSchema` clauses.
+ * As is, this works correctly in most realistic use-cases.
+ *
+ * One special case this makes is if the result of NodeFromSchema contains TreeNode, this must be an under constrained schema, so the result is set to never.
+ * Note that applying UnionToIntersection on the result of NodeFromSchema<T> does not work since it breaks booleans.
+ *
  * @public
  */
-export type InsertableTypedNode<T extends TreeNodeSchema> =
-	| (T extends { implicitlyConstructable: true } ? NodeBuilderData<T> : never)
-	| Unhydrated<NodeFromSchema<T>>;
+export type InsertableTypedNode<
+	TSchema extends TreeNodeSchema,
+	T = UnionToIntersection<TSchema>,
+> =
+	| (T extends TreeNodeSchema<string, NodeKind, TreeNode | TreeLeafValue, never, true>
+			? NodeBuilderData<T>
+			: never)
+	| (T extends TreeNodeSchema
+			? Unhydrated<TreeNode extends NodeFromSchema<T> ? never : NodeFromSchema<T>>
+			: never);
 
 /**
  * Given a node's schema, return the corresponding object from which the node could be built.
@@ -471,7 +663,7 @@ export type InsertableTypedNode<T extends TreeNodeSchema> =
 export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 	string,
 	NodeKind,
-	unknown,
+	TreeNode | TreeLeafValue,
 	infer TBuild
 >
 	? TBuild

package/src/simple-tree/toMapTree.ts

@@ -726,6 +726,7 @@ function tryGetInnerNode(target: unknown): InnerNode | undefined {
  * Content which can be used to build a node.
  * @remarks
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
+ * @system @alpha
  */
 export type FactoryContent =
 	| IFluidHandle
@@ -744,12 +745,14 @@ export type FactoryContent =
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
  *
  * Supports object and map nodes.
+ * @system @alpha
  */
-type FactoryContentObject = {
+export type FactoryContentObject = {
 	readonly [P in string]?: InsertableContent;
 };
 
 /**
  * Content which can be inserted into a tree.
+ * @system @alpha
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;