@fluidframework/tree 2.53.1 → 2.61.0-355054

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

@@ -25,6 +25,12 @@ export interface SimpleNodeSchemaBase<
 
 	/**
 	 * User-provided {@link NodeSchemaMetadata} for this schema.
+	 *
+	 * @remarks
+	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
+	 * Different clients in the same collaborative session may see different metadata for the same field.
+	 *
+	 * Set via {@link NodeSchemaOptions.metadata}.
 	 */
 	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
 }

package/src/simple-tree/fieldSchema.ts

@@ -187,7 +187,9 @@ export interface FieldProps<TCustomMetadata = unknown> {
 export interface FieldPropsAlpha<TCustomMetadata = unknown>
 	extends FieldProps<TCustomMetadata> {
 	/**
-	 * The persisted metadata for this schema element.
+	 * The persisted metadata for a field schema.
+	 * @remarks
+	 * Sets {@link SimpleFieldSchema.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
@@ -428,9 +430,6 @@ export class FieldSchemaAlpha<
 	 */
 	public readonly allowedTypesMetadata: AllowedTypesMetadata;
 
-	/**
-	 * Persisted metadata for this field schema.
-	 */
 	public get persistedMetadata(): JsonCompatibleReadOnlyObject | undefined {
 		return this.propsAlpha?.persistedMetadata;
 	}

package/src/simple-tree/index.ts

@@ -70,6 +70,7 @@ export {
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
+	SchemaFactoryBeta,
 	SchemaFactoryAlpha,
 	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
@@ -161,6 +162,8 @@ export {
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 	type SchemaStaticsAlpha,
+	KeyEncodingOptions,
+	type TreeParsingOptions,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -184,11 +184,10 @@ function createRecordNodeProxy(
 
 			const innerNode = getOrCreateInnerNode(proxy);
 			const field = innerNode.tryGetField(brand(key)) as FlexTreeOptionalField | undefined;
-			if (field === undefined) {
-				return false;
+			if (field !== undefined) {
+				field.editor.set(undefined, field.length === 0);
 			}
 
-			field.editor.set(undefined, field.length === 0);
 			return true;
 		},
 	});

package/src/simple-tree/simpleSchema.ts

@@ -26,6 +26,15 @@ export interface SimpleNodeSchemaBaseAlpha<
 > extends SimpleNodeSchemaBase<TNodeKind, TCustomMetadata> {
 	/**
 	 * Persisted metadata for this node schema.
+	 * @remarks
+	 * While this can be stored in the document, not all versions / configurations will do so.
+	 * Additionally, this is not part of {@link TreeView.compatibility|schema compatibility}, so different clients
+	 * (even within the same collaborative session) may see different `persistedMetadata` for the same node.
+	 * Specified using {@link NodeSchemaOptionsAlpha.persistedMetadata}.
+	 * @privateRemarks
+	 * How/when this gets updated in documents,
+	 * and how to read it from documents should be documented here when this feature is more mature and these questions have good answers.
+	 * If this does end up getting reflected in some compatibility value, that should also be documented.
 	 */
 	readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined;
 }
@@ -184,6 +193,9 @@ export interface SimpleFieldSchema {
 
 	/**
 	 * Persisted metadata for this field schema.
+	 * @remarks
+	 * Like {@link SimpleNodeSchemaBaseAlpha.persistedMetadata} but for fields.
+	 * Set via {@link FieldPropsAlpha.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }

package/src/simple-tree/toStoredSchema.ts

@@ -161,9 +161,6 @@ export const convertFieldKind: ReadonlyMap<FieldKind, FlexFieldKind> = new Map<
  * Converts a {@link TreeNodeSchema} into a {@link TreeNodeStoredSchema}.
  * @privateRemarks
  * TODO: Persist node metadata once schema FormatV2 is supported.
- *
- * TODO: AB#43548: Using a stored schema for unhydrated flex trees does not handle schema evolution features like "allowUnknownOptionalFields".
- * Usage of this and the conversion which wrap it should be audited and reduced.
  */
 export function getStoredSchema(
 	schema: SimpleNodeSchema,