@fluidframework/tree 2.113.1 → 2.114.0

package/src/text/textDomainFormattedDefault.ts

@@ -3,12 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import {
-	enumFromStrings,
-	SchemaFactory,
-	SchemaFactoryAlpha,
-	SchemaFactoryBeta,
-} from "../simple-tree/index.js";
+import { enumFromStrings, SchemaFactory, SchemaFactoryBeta } from "../simple-tree/index.js";
 import type {
 	TreeNodeFromImplicitAllowedTypes,
 	InsertableTreeNodeFromImplicitAllowedTypes,
@@ -19,7 +14,7 @@ import { FormattedTextAsTree } from "./textDomainFormatted.js";
 /**
  * Schema factory for default formatted text types which are not generic.
  */
-const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted.default");
+const sf = new SchemaFactoryBeta("com.fluidframework.text.formatted.default");
 
 const defaultFormat = {
 	bold: false,
@@ -30,9 +25,8 @@ const defaultFormat = {
 } as const;
 
 /**
- * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * A default parameterization of the generic {@link FormattedTextAsTree} with hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
  * @remarks
- * This is a default parameterization of the generic {@link FormattedTextAsTree} with hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
  * It is unlikely this meets the needs of most users, but it can serve as an unstable example of how to use the generic {@link FormattedTextAsTree}.
  * @internal
  */
@@ -49,9 +43,10 @@ export namespace FormattedTextAsTreeDefault {
 
 	/**
 	 * Formatting options for characters.
+	 * @sealed
 	 * @internal
 	 */
-	export class CharacterFormat extends sf.objectAlpha("CharacterFormat", {
+	export class CharacterFormat extends sf.object("CharacterFormat", {
 		bold: SchemaFactory.boolean,
 		italic: SchemaFactory.boolean,
 		underline: SchemaFactory.boolean,
@@ -80,6 +75,7 @@ export namespace FormattedTextAsTreeDefault {
 	]);
 	/**
 	 * {@inheritdoc FormattedTextAsTreeDefault.(LineTag:variable)}
+	 * @sealed
 	 * @internal
 	 */
 	export type LineTag = TreeNodeFromImplicitAllowedTypes<typeof LineTag.schema>;
@@ -93,6 +89,7 @@ export namespace FormattedTextAsTreeDefault {
 	 * The optional indent level mirrors Quill's indent attribute,
 	 * which is applies to the line before the line break.
 	 * Any tagged line can be indented independently.
+	 * @sealed
 	 * @internal
 	 */
 	export class StringLineAtom extends sf.object("StringLineAtom", {
@@ -104,6 +101,7 @@ export namespace FormattedTextAsTreeDefault {
 
 	/**
 	 * Types of "atoms" that make up the text.
+	 * @sealed
 	 * @internal
 	 */
 	export const StringAtomContent = [
@@ -112,37 +110,48 @@ export namespace FormattedTextAsTreeDefault {
 	] as const;
 	/**
 	 * {@inheritdoc FormattedTextAsTreeDefault.(StringAtomContent:variable)}
+	 * @sealed
 	 * @internal
 	 */
 	export type StringAtomContent = TreeNodeFromImplicitAllowedTypes<typeof StringAtomContent>;
 
 	/**
 	 * Statics for text nodes.
+	 * @sealed
 	 * @internal
 	 */
-	export type Statics<TTree = Tree> = FormattedTextAsTree.Statics<TTree>;
+	export type Statics<TTree = Tree> = FormattedTextAsTree.Statics<
+		TTree,
+		typeof CharacterFormat
+	>;
 
 	/**
 	 * Insertable shape for a formatted text atom used by {@link FormattedTextAsTree.Members.insertWithFormattingAt}.
+	 * @sealed
 	 * @internal
 	 */
 	export type FormattedAtomInsertable = FormattedTextAsTree.FormattedAtom<
 		InsertableTreeNodeFromImplicitAllowedTypes<typeof CharacterFormat>,
-		InsertableTreeNodeFromImplicitAllowedTypes<FormattedTextAtoms>
+		InsertableTreeNodeFromImplicitAllowedTypes<TextAtomSchemas>
 	>;
 
 	/**
 	 * Helper for expressing the full set of formatted text atoms for a given schema.
 	 * @privateRemarks
 	 * Eventually this should probably be given a better name and/or made a system type in a system namespace.
+	 * @sealed
 	 * @internal
 	 */
-	export type FormattedTextAtoms = FormattedTextAsTree.FormattedTextAtoms<
-		[typeof StringLineAtom]
-	>;
+	export type TextAtomSchemas = FormattedTextAsTree.TextAtomSchemas<[typeof StringLineAtom]>;
 
+	/**
+	 * The schema produced using {@link FormattedTextAsTree.createSchema} with hard-coded assumptions
+	 * about what kind of embedded content and what kind of formatting is supported.
+	 * @sealed
+	 * @internal
+	 */
 	export class Tree extends FormattedTextAsTree.createSchema(
-		new SchemaFactoryBeta("default"),
+		sf,
 		CharacterFormat,
 		[StringLineAtom],
 		defaultFormat,

package/src/treeDataStore.ts

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidLoadable } from "@fluidframework/core-interfaces";
+import type { DataStoreKind } from "@fluidframework/driver-definitions/internal";
+import type {
+	SharedObjectCreator,
+	SharedObjectKey,
+	SharedObjectRegistry,
+	SharedObjectKindAlpha,
+	DataStoreOptions,
+} from "@fluidframework/shared-object-base/internal";
+import {
+	sharedObjectRegistryFromIterable,
+	defineDataStore,
+} from "@fluidframework/shared-object-base/internal";
+
+import type {
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	ITree,
+	TreeView,
+	TreeViewConfiguration,
+} from "./simple-tree/index.js";
+import { SharedTreeAlpha } from "./treeFactory.js";
+
+/**
+ * Options for {@link defineTreeDataStore}.
+ * @input
+ * @alpha
+ */
+export interface TreeDataStoreOptions<TSchema extends ImplicitFieldSchema>
+	extends Pick<DataStoreOptions<never, never>, "type"> {
+	/**
+	 * Configuration for the tree view to be used in this data store.
+	 */
+	readonly config: TreeViewConfiguration<TSchema>;
+
+	/**
+	 * If provided, used to initialize the tree content when creating a new instance of the data store.
+	 */
+	readonly initializer?: (
+		creator: SharedObjectCreator,
+	) => InsertableTreeFieldFromImplicitField<TSchema>;
+
+	/**
+	 * If provided, must include at least a SharedTree kind in the registry.
+	 * @remarks
+	 * {@link configuredSharedTree} can be used to customize the SharedTree kind used in the registry.
+	 */
+	readonly registry?: Iterable<SharedObjectKindAlpha<IFluidLoadable>> | SharedObjectRegistry;
+
+	readonly key?: SharedObjectKey<ITree>;
+}
+
+/**
+ * Defines a {@link @fluidframework/driver-definitions#DataStoreKind} for a simple tree data store.
+ * @remarks
+ * This is a simple tree specific wrapper around {@link @fluidframework/shared-object-base#defineDataStore}.
+ * Use {@link @fluidframework/shared-object-base#defineDataStore} directly if more control is needed, even if still just using tree.
+ *
+ * This uses {@link instantiateTreeFirstTime} to create the tree, and optionally initialize it.
+ * @alpha
+ */
+export function defineTreeDataStore<const TSchema extends ImplicitFieldSchema>(
+	options: TreeDataStoreOptions<TSchema>,
+): DataStoreKind<TreeView<TSchema>> {
+	const registry: SharedObjectRegistry =
+		typeof options.registry === "function"
+			? options.registry
+			: sharedObjectRegistryFromIterable([...(options.registry ?? [SharedTreeAlpha])]);
+
+	const result = defineDataStore<TreeView<TSchema>, ITree>({
+		type: options.type,
+		registry,
+		async instantiateFirstTime(
+			rootCreator: SharedObjectCreator,
+			creator: SharedObjectCreator,
+		): Promise<ITree> {
+			return instantiateTreeFirstTime(
+				rootCreator,
+				creator,
+				options.key ?? SharedTreeAlpha,
+				options,
+			);
+		},
+		async view(tree): Promise<TreeView<TSchema>> {
+			const view = tree.viewWith(options.config);
+			return view;
+		},
+	});
+	return result;
+}
+
+/**
+ * Simple tree instantiation helper.
+ * @remarks
+ * This is used by {@link defineTreeDataStore}, but can also be used in custom data stores with {@link @fluidframework/shared-object-base#defineDataStore}.
+ * Typically used to implement {@link @fluidframework/shared-object-base#DataStoreOptions.instantiateFirstTime} to create the tree and optionally initialize it.
+ * @alpha
+ */
+export async function instantiateTreeFirstTime<TSchema extends ImplicitFieldSchema>(
+	rootCreator: SharedObjectCreator,
+	creator: SharedObjectCreator,
+	treeKind: SharedObjectKey<ITree>,
+	options: Pick<TreeDataStoreOptions<TSchema>, "config" | "initializer">,
+): Promise<ITree> {
+	const tree = await rootCreator.createSharedObject(treeKind);
+	initializeTreeFirstTime(tree, options, creator);
+	return tree;
+}
+
+function initializeTreeFirstTime<TSchema extends ImplicitFieldSchema>(
+	tree: ITree,
+	options: Pick<TreeDataStoreOptions<TSchema>, "config" | "initializer">,
+	creator: SharedObjectCreator,
+): void {
+	if (options.initializer !== undefined) {
+		const view = tree.viewWith(options.config);
+		view.initialize(options.initializer(creator));
+		view.dispose();
+	}
+}

package/src/treeFactory.ts

@@ -13,6 +13,7 @@ import {
 	type SharedKernelFactory,
 	type SharedObjectOptions,
 	type FactoryOut,
+	type SharedObjectKindAlpha,
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -111,7 +112,14 @@ function treeKernelFactory(
  * of objects, arrays, and other data types.
  * @legacy @beta
  */
-export const SharedTree = configuredSharedTree({});
+export const SharedTree: ISharedObjectKind<ITree> & SharedObjectKind<ITree> =
+	configuredSharedTree({});
+
+/**
+ * {@link SharedTree} but without legacy types, and with alpha types.
+ * @alpha
+ */
+export const SharedTreeAlpha: SharedObjectKindAlpha<ITree> = configuredSharedTree({});
 
 /**
  * {@link SharedTree} but allowing a non-default configuration.
@@ -189,14 +197,14 @@ export function configuredSharedTreeAlpha(
  */
 export function configuredSharedTree(
 	options: SharedTreeOptions,
-): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
+): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {
 	const internalOptions = resolveOptions(options);
 	return configuredSharedTreeInternal(internalOptions);
 }
 
 export function configuredSharedTreeInternal(
 	options: SharedTreeOptionsInternal,
-): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
+): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {
 	const sharedObjectOptions: SharedObjectOptions<ITree> = {
 		type: SharedTreeFactoryType,
 		attributes: SharedTreeAttributes,