From 216600c1096cf129895661031f025ea5de7f2905 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Sat, 31 Jan 2026 00:59:30 +0000 Subject: [PATCH 01/23] feat(tree): Promote TableSchema APIs to beta --- .../dds/tree/api-report/tree.alpha.api.md | 5 +- packages/dds/tree/api-report/tree.beta.api.md | 142 ++++++++++++++++++ .../tree/api-report/tree.legacy.beta.api.md | 142 ++++++++++++++++++ packages/dds/tree/src/tableSchema.ts | 81 +++++----- .../api-report/fluid-framework.alpha.api.md | 5 +- .../api-report/fluid-framework.beta.api.md | 142 ++++++++++++++++++ .../fluid-framework.legacy.beta.api.md | 142 ++++++++++++++++++ 7 files changed, 612 insertions(+), 47 deletions(-) diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index 9fc00fc6225c..1ff8aa35e945 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -1208,7 +1208,7 @@ export interface SnapshotFileSystem { }): void; } -// @alpha @system +// @beta @system export namespace System_TableSchema { // @sealed @system export type ColumnSchemaBase = ReturnType>; @@ -1227,7 +1227,6 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @sealed export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; @@ -1354,7 +1353,7 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @alpha +// @beta export namespace TableSchema { // @input export interface CellKey { diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index 2f9c6e1502f2..6f1972518b53 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -575,6 +575,68 @@ export function singletonSchema, true, Record, undefined>; +// @beta @system +export namespace System_TableSchema { + // @sealed @system + export type ColumnSchemaBase = ReturnType>; + // @system + export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system + export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + }>; + // @system + export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; + }>; + // @system + export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { + create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; + } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); + // @system + export type DefaultPropsType = ReturnType>; + // @system + export interface OptionsWithCellSchema { + readonly cell: TCellSchema; + } + // @system + export interface OptionsWithSchemaFactory { + readonly schemaFactory: TSchemaFactory; + } + // @system + export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { + moveToEnd(sourceIndex: number): void; + moveToStart(sourceIndex: number): void; + moveToIndex(sourceIndex: number, destinationIndex: number): void; + moveRangeToEnd(startIndex: number, endIndex: number): void; + moveRangeToStart(startIndex: number, endIndex: number): void; + moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; + }; + // @sealed @system + export type RowSchemaBase = ReturnType>; + // @system + export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @sealed @system + export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; +} + // @public @system export namespace System_Unsafe { // @system @@ -658,6 +720,86 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } +// @beta +export namespace TableSchema { + // @input + export interface CellKey { + readonly column: string | number | TreeNodeFromImplicitAllowedTypes; + readonly row: string | number | TreeNodeFromImplicitAllowedTypes; + } + // @sealed + export interface Column { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.ColumnSchemaBase; + // @input + export interface InsertColumnsParameters { + readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; + readonly index?: number | undefined; + } + // @input + export interface InsertRowsParameters { + readonly index?: number | undefined; + readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; + } + // @sealed + export interface Row { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.RowSchemaBase; + // @input + export interface SetCellParameters { + readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; + readonly key: CellKey; + } + // @sealed + export interface Table, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns: System_TableSchema.RearrangeableList; + getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; + insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; + removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + readonly rows: System_TableSchema.RearrangeableList; + setCell(params: SetCellParameters): void; + } + export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + }): System_TableSchema.TableSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly row: TRow; + }): System_TableSchema.TableSchemaBase, TRow>; + export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + readonly row: TRow; + }): System_TableSchema.TableSchemaBase; + // @input + export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns?: Iterable> | undefined; + readonly rows?: Iterable> | undefined; + } +} + // @public export type TransactionConstraint = NodeInDocumentConstraint; diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index 0e476c9cf978..9081f61547c2 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -587,6 +587,68 @@ export function singletonSchema, true, Record, undefined>; +// @beta @system +export namespace System_TableSchema { + // @sealed @system + export type ColumnSchemaBase = ReturnType>; + // @system + export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system + export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + }>; + // @system + export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; + }>; + // @system + export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { + create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; + } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); + // @system + export type DefaultPropsType = ReturnType>; + // @system + export interface OptionsWithCellSchema { + readonly cell: TCellSchema; + } + // @system + export interface OptionsWithSchemaFactory { + readonly schemaFactory: TSchemaFactory; + } + // @system + export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { + moveToEnd(sourceIndex: number): void; + moveToStart(sourceIndex: number): void; + moveToIndex(sourceIndex: number, destinationIndex: number): void; + moveRangeToEnd(startIndex: number, endIndex: number): void; + moveRangeToStart(startIndex: number, endIndex: number): void; + moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; + }; + // @sealed @system + export type RowSchemaBase = ReturnType>; + // @system + export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @sealed @system + export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; +} + // @public @system export namespace System_Unsafe { // @system @@ -670,6 +732,86 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } +// @beta +export namespace TableSchema { + // @input + export interface CellKey { + readonly column: string | number | TreeNodeFromImplicitAllowedTypes; + readonly row: string | number | TreeNodeFromImplicitAllowedTypes; + } + // @sealed + export interface Column { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.ColumnSchemaBase; + // @input + export interface InsertColumnsParameters { + readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; + readonly index?: number | undefined; + } + // @input + export interface InsertRowsParameters { + readonly index?: number | undefined; + readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; + } + // @sealed + export interface Row { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.RowSchemaBase; + // @input + export interface SetCellParameters { + readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; + readonly key: CellKey; + } + // @sealed + export interface Table, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns: System_TableSchema.RearrangeableList; + getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; + insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; + removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + readonly rows: System_TableSchema.RearrangeableList; + setCell(params: SetCellParameters): void; + } + export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + }): System_TableSchema.TableSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly row: TRow; + }): System_TableSchema.TableSchemaBase, TRow>; + export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + readonly row: TRow; + }): System_TableSchema.TableSchemaBase; + // @input + export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns?: Iterable> | undefined; + readonly rows?: Iterable> | undefined; + } +} + // @public export type TransactionConstraint = NodeInDocumentConstraint; diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 46baf552dbee..5dfc04dbbd2f 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -84,12 +84,21 @@ export interface RowPrivate< /** * Not intended for use outside of this package. * + * @remarks + * + * Orphaned Cells: + * There is a concept of cells in the table becoming "orphaned.". + * An orphaned cell is a cell that does not correspond to a valid row and column. + * In order to preserve the invariant that all cells must have a valid row and column, table operations + * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that + * guard transactions from producing orphaned cells. + * * @privateRemarks * This namespace is a collection of internal system types relate to {@link TableSchema}. * This namespace should be strictly type-exported by the package. * All members should be tagged with `@system`. * - * @system @alpha + * @system @beta */ export namespace System_TableSchema { /** @@ -100,7 +109,7 @@ export namespace System_TableSchema { * Note: this can't reasonably be implemented via `Pick>` because we only want to include the * subset of its method overloads which do not support moving items between lists. * - * @alpha @system + * @beta @system */ export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { @@ -128,7 +137,7 @@ export namespace System_TableSchema { * Longer term, it would be better to simply omit "props" altogether by default. * For now, this ensures that the user doesn't have to specify a "props" entry when initializing column/row nodes * and ensures that they cannot set anything that might conflict with future evolutions of the schema. - * @system @alpha + * @system @beta */ export type DefaultPropsType = ReturnType>; @@ -136,7 +145,7 @@ export namespace System_TableSchema { * A base interface for factory input options which include an schema factory. * @remarks This interface should not be referenced directly. * @privateRemarks This interface primarily exists to provide a single home for property documentation. - * @system @alpha + * @system @beta */ export interface OptionsWithSchemaFactory { /** @@ -151,7 +160,7 @@ export namespace System_TableSchema { * A base interface for factory input options which include the table cell schema. * @remarks This interface should not be referenced directly. * @privateRemarks This interface primarily exists to provide a single home for property documentation. - * @system @alpha + * @system @beta */ export interface OptionsWithCellSchema { /** @@ -165,7 +174,7 @@ export namespace System_TableSchema { /** * Base options for creating table column schema. * @remarks Includes parameters common to all column factory overloads. - * @system @alpha + * @system @beta */ export type CreateColumnOptionsBase< TUserScope extends string = string, @@ -175,7 +184,7 @@ export namespace System_TableSchema { /** * Factory for creating column schema. - * @system @alpha + * @system @beta */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createColumnSchema< @@ -291,7 +300,7 @@ export namespace System_TableSchema { /** * Base column schema type. - * @sealed @system @alpha + * @sealed @system @beta */ export type ColumnSchemaBase< TUserScope extends string = string, @@ -306,7 +315,7 @@ export namespace System_TableSchema { /** * Base options for creating table row schema. * @remarks Includes parameters common to all row factory overloads. - * @system @alpha + * @system @beta */ export type CreateRowOptionsBase< TUserScope extends string = string, @@ -316,7 +325,7 @@ export namespace System_TableSchema { /** * Factory for creating row schema. - * @sealed @alpha + * @beta */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createRowSchema< @@ -444,7 +453,7 @@ export namespace System_TableSchema { /** * Base row schema type. - * @sealed @system @alpha + * @sealed @system @beta */ export type RowSchemaBase< TUserScope extends string = string, @@ -459,7 +468,7 @@ export namespace System_TableSchema { /** * Base options for creating table schema. * @remarks Includes parameters common to all table factory overloads. - * @system @alpha + * @system @beta */ export type TableFactoryOptionsBase< TUserScope extends string = string, @@ -469,7 +478,7 @@ export namespace System_TableSchema { /** * Factory for creating table schema. - * @system @alpha + * @system @beta */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createTableSchema< @@ -1290,7 +1299,7 @@ export namespace System_TableSchema { /** * Base row schema type. - * @sealed @system @alpha + * @sealed @system @beta */ export type TableSchemaBase< TUserScope extends string, @@ -1336,11 +1345,6 @@ function removeRangeFromArray( * * @remarks * - * WARNING: These APIs are in preview and are subject to change. - * Until these APIs have stabilized, it is not recommended to use them in production code. - * There may be breaking changes to these APIs and their underlying data format. - * Using these APIs in production code may result in data loss or corruption. - * * The primary APIs for create tabular data schema are: * * - {@link TableSchema.(table:1)} @@ -1362,11 +1366,6 @@ function removeRangeFromArray( * Column and Row schema created using these APIs are extensible via the `props` field. * This allows association of additional properties with column and row nodes. * - * There is a concept of cells in the table becoming "orphaned.". An orphaned cell is a cell that does not correspond to a valid row and column. - * In order to preserve the invariant that all cells must have a valid row and column, table operations - * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that - * guards transactions from producing orphaned cells. - * * @example Defining a Table schema * * ```typescript @@ -1442,7 +1441,7 @@ function removeRangeFromArray( * The above examples are backed by tests in `tableSchema.spec.ts`. * Those tests and these examples should be kept in-sync to ensure that the examples are correct. * - * @alpha + * @beta */ export namespace TableSchema { // #region Column @@ -1452,7 +1451,7 @@ export namespace TableSchema { * @remarks Implemented by the schema class returned from {@link TableSchema.(column:2)}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the column. - * @sealed @alpha + * @sealed @beta */ export interface Column< // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reserving this for future use. @@ -1480,7 +1479,7 @@ export namespace TableSchema { * Factory for creating new table column schema. * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. - * @alpha + * @beta */ export function column< const TUserScope extends string, @@ -1501,7 +1500,7 @@ export namespace TableSchema { * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the column. - * @alpha + * @beta */ export function column< const TUserScope extends string, @@ -1541,7 +1540,7 @@ export namespace TableSchema { * @remarks Implemented by the schema class returned from {@link TableSchema.(row:2)}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the row. - * @sealed @alpha + * @sealed @beta */ export interface Row< // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reserving this for future use. @@ -1569,7 +1568,7 @@ export namespace TableSchema { * Factory for creating new table column schema. * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. - * @alpha + * @beta */ export function row< const TUserScope extends string, @@ -1586,7 +1585,7 @@ export namespace TableSchema { * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the row. - * @alpha + * @beta */ export function row< const TUserScope extends string, @@ -1623,7 +1622,7 @@ export namespace TableSchema { /** * A key to uniquely identify a cell within a table. - * @input @alpha + * @input @beta */ export interface CellKey< TColumn extends ImplicitAllowedTypes, @@ -1642,7 +1641,7 @@ export namespace TableSchema { /** * {@link TableSchema.Table.insertColumns} parameters. - * @input @alpha + * @input @beta */ export interface InsertColumnsParameters { /** @@ -1659,7 +1658,7 @@ export namespace TableSchema { /** * {@link TableSchema.Table.insertRows} parameters. - * @input @alpha + * @input @beta */ export interface InsertRowsParameters { /** @@ -1676,7 +1675,7 @@ export namespace TableSchema { /** * {@link TableSchema.Table.setCell} parameters. - * @input @alpha + * @input @beta */ export interface SetCellParameters< TCell extends ImplicitAllowedTypes, @@ -1706,7 +1705,7 @@ export namespace TableSchema { * @typeParam TColumn - The type of the columns in the table. * @typeParam TRow - The type of the rows in the table. * - * @sealed @alpha + * @sealed @beta */ export interface Table< TUserScope extends string, @@ -1872,7 +1871,7 @@ export namespace TableSchema { /** * Input parameters for {@link TableSchema.Table}'s `create` factory method. - * @input @alpha + * @input @beta */ export interface TableFactoryMethodParameters< TUserScope extends string, @@ -1899,7 +1898,7 @@ export namespace TableSchema { * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * The resulting schema will have an identifier of the form: `com.fluidframework.table<${TUserScope}>.Table`. * @typeParam TCell - The type of the cells in the table. - * @alpha + * @beta */ export function table< const TUserScope extends string, @@ -1926,7 +1925,7 @@ export namespace TableSchema { * The resulting schema will have an identifier of the form: `com.fluidframework.table<${TUserScope}>.Table`. * @typeParam TCell - The type of the cells in the table. * @typeParam TColumn - The type of the columns in the table. - * @alpha + * @beta */ export function table< const TUserScope extends string, @@ -1952,7 +1951,7 @@ export namespace TableSchema { * The resulting schema will have an identifier of the form: `com.fluidframework.table<${TUserScope}>.Table`. * @typeParam TCell - The type of the cells in the table. * @typeParam TRow - The type of the rows in the table. - * @alpha + * @beta */ export function table< const TUserScope extends string, @@ -1983,7 +1982,7 @@ export namespace TableSchema { * @typeParam TCell - The type of the cells in the table. * @typeParam TColumn - The type of the columns in the table. * @typeParam TRow - The type of the rows in the table. - * @alpha + * @beta */ export function table< const TUserScope extends string, diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 36792f9900cb..2804b39c5ca5 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -1586,7 +1586,7 @@ export interface SnapshotFileSystem { }): void; } -// @alpha @system +// @beta @system export namespace System_TableSchema { // @sealed @system export type ColumnSchemaBase = ReturnType>; @@ -1605,7 +1605,6 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @sealed export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; @@ -1732,7 +1731,7 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @alpha +// @beta export namespace TableSchema { // @input export interface CellKey { diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index 264c33b1e826..d95fdeab9150 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -947,6 +947,68 @@ export function singletonSchema, true, Record, undefined>; +// @beta @system +export namespace System_TableSchema { + // @sealed @system + export type ColumnSchemaBase = ReturnType>; + // @system + export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system + export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + }>; + // @system + export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; + }>; + // @system + export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { + create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; + } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); + // @system + export type DefaultPropsType = ReturnType>; + // @system + export interface OptionsWithCellSchema { + readonly cell: TCellSchema; + } + // @system + export interface OptionsWithSchemaFactory { + readonly schemaFactory: TSchemaFactory; + } + // @system + export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { + moveToEnd(sourceIndex: number): void; + moveToStart(sourceIndex: number): void; + moveToIndex(sourceIndex: number, destinationIndex: number): void; + moveRangeToEnd(startIndex: number, endIndex: number): void; + moveRangeToStart(startIndex: number, endIndex: number): void; + moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; + }; + // @sealed @system + export type RowSchemaBase = ReturnType>; + // @system + export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @sealed @system + export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; +} + // @public @system export namespace System_Unsafe { // @system @@ -1030,6 +1092,86 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } +// @beta +export namespace TableSchema { + // @input + export interface CellKey { + readonly column: string | number | TreeNodeFromImplicitAllowedTypes; + readonly row: string | number | TreeNodeFromImplicitAllowedTypes; + } + // @sealed + export interface Column { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.ColumnSchemaBase; + // @input + export interface InsertColumnsParameters { + readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; + readonly index?: number | undefined; + } + // @input + export interface InsertRowsParameters { + readonly index?: number | undefined; + readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; + } + // @sealed + export interface Row { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.RowSchemaBase; + // @input + export interface SetCellParameters { + readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; + readonly key: CellKey; + } + // @sealed + export interface Table, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns: System_TableSchema.RearrangeableList; + getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; + insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; + removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + readonly rows: System_TableSchema.RearrangeableList; + setCell(params: SetCellParameters): void; + } + export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + }): System_TableSchema.TableSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly row: TRow; + }): System_TableSchema.TableSchemaBase, TRow>; + export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + readonly row: TRow; + }): System_TableSchema.TableSchemaBase; + // @input + export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns?: Iterable> | undefined; + readonly rows?: Iterable> | undefined; + } +} + // @public export interface Tagged { // (undocumented) diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index e3d6fed2cb9f..950128b24a91 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -1307,6 +1307,68 @@ export function singletonSchema, true, Record, undefined>; +// @beta @system +export namespace System_TableSchema { + // @sealed @system + export type ColumnSchemaBase = ReturnType>; + // @system + export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system + export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + }>; + // @system + export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { + readonly id?: string | undefined; + readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; + } & (FieldHasDefault extends true ? { + props?: InsertableTreeFieldFromImplicitField | undefined; + } : { + props: InsertableTreeFieldFromImplicitField; + }), true, { + readonly props: TPropsSchema; + readonly id: FieldSchema_2, unknown>; + readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; + }>; + // @system + export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { + create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; + } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); + // @system + export type DefaultPropsType = ReturnType>; + // @system + export interface OptionsWithCellSchema { + readonly cell: TCellSchema; + } + // @system + export interface OptionsWithSchemaFactory { + readonly schemaFactory: TSchemaFactory; + } + // @system + export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { + moveToEnd(sourceIndex: number): void; + moveToStart(sourceIndex: number): void; + moveToIndex(sourceIndex: number, destinationIndex: number): void; + moveRangeToEnd(startIndex: number, endIndex: number): void; + moveRangeToStart(startIndex: number, endIndex: number): void; + moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; + }; + // @sealed @system + export type RowSchemaBase = ReturnType>; + // @system + export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @sealed @system + export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; +} + // @public @system export namespace System_Unsafe { // @system @@ -1390,6 +1452,86 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } +// @beta +export namespace TableSchema { + // @input + export interface CellKey { + readonly column: string | number | TreeNodeFromImplicitAllowedTypes; + readonly row: string | number | TreeNodeFromImplicitAllowedTypes; + } + // @sealed + export interface Column { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; + export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.ColumnSchemaBase; + // @input + export interface InsertColumnsParameters { + readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; + readonly index?: number | undefined; + } + // @input + export interface InsertRowsParameters { + readonly index?: number | undefined; + readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; + } + // @sealed + export interface Row { + readonly id: string; + get props(): TreeFieldFromImplicitField; + set props(value: InsertableTreeFieldFromImplicitField); + } + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; + export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { + readonly props: TProps; + }): System_TableSchema.RowSchemaBase; + // @input + export interface SetCellParameters { + readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; + readonly key: CellKey; + } + // @sealed + export interface Table, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns: System_TableSchema.RearrangeableList; + getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; + getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; + insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; + insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; + removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; + removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; + removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; + readonly rows: System_TableSchema.RearrangeableList; + setCell(params: SetCellParameters): void; + } + export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + }): System_TableSchema.TableSchemaBase>; + export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly row: TRow; + }): System_TableSchema.TableSchemaBase, TRow>; + export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { + readonly column: TColumn; + readonly row: TRow; + }): System_TableSchema.TableSchemaBase; + // @input + export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { + readonly columns?: Iterable> | undefined; + readonly rows?: Iterable> | undefined; + } +} + // @public export interface Tagged { // (undocumented) From 45c8aee7ea890a59172c8d21470b7ba10365fa14 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:59:50 +0000 Subject: [PATCH 02/23] docs: Add warning about extranious modification --- packages/dds/tree/src/tableSchema.ts | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 5dfc04dbbd2f..1c6981af006d 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -84,7 +84,10 @@ export interface RowPrivate< /** * Not intended for use outside of this package. * - * @remarks + * @privateRemarks + * This namespace is a collection of internal system types relate to {@link TableSchema}. + * This namespace should be strictly type-exported by the package. + * All members should be tagged with `@system`. * * Orphaned Cells: * There is a concept of cells in the table becoming "orphaned.". @@ -93,11 +96,6 @@ export interface RowPrivate< * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that * guard transactions from producing orphaned cells. * - * @privateRemarks - * This namespace is a collection of internal system types relate to {@link TableSchema}. - * This namespace should be strictly type-exported by the package. - * All members should be tagged with `@system`. - * * @system @beta */ export namespace System_TableSchema { @@ -1345,6 +1343,11 @@ function removeRangeFromArray( * * @remarks * + * Note: The APIs produced by this module ensure various tabular data invariants are maintained that the raw, underlying tree structures do not. + * For example, they ensure that cells always correspond to existing rows and columns (and do not become "orphaned" due to row/column deletion, etc.). + * For this reason, direct manipulation of the underlying tree structures is not supported. + * To modify the data, only the APIs provided here may be used. + * * The primary APIs for create tabular data schema are: * * - {@link TableSchema.(table:1)} From 4ff1a5dbfed91773619859b5633e0b9794750ee9 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:02:12 -0800 Subject: [PATCH 03/23] docs: Fix typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- packages/dds/tree/src/tableSchema.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 1c6981af006d..feb6bec711dd 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -90,7 +90,7 @@ export interface RowPrivate< * All members should be tagged with `@system`. * * Orphaned Cells: - * There is a concept of cells in the table becoming "orphaned.". + * There is a concept of cells in the table becoming "orphaned". * An orphaned cell is a cell that does not correspond to a valid row and column. * In order to preserve the invariant that all cells must have a valid row and column, table operations * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that From e6b281f843976b42fe30cc246d0bca107a49bf52 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:02:49 -0800 Subject: [PATCH 04/23] docs: Add missing `@system` tag Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- packages/dds/tree/src/tableSchema.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index feb6bec711dd..ce8f4a567b55 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -323,7 +323,7 @@ export namespace System_TableSchema { /** * Factory for creating row schema. - * @beta + * @system @beta */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createRowSchema< From 0530cff06f45a2df26e0d4b8cb64011f0ffcf6c3 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 18:05:00 +0000 Subject: [PATCH 05/23] docs: Update comment --- packages/dds/tree/src/tableSchema.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index ce8f4a567b55..9a9df2e8681e 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -90,7 +90,7 @@ export interface RowPrivate< * All members should be tagged with `@system`. * * Orphaned Cells: - * There is a concept of cells in the table becoming "orphaned". + * Without safeguards, it is possible for cells to become "orphaned". * An orphaned cell is a cell that does not correspond to a valid row and column. * In order to preserve the invariant that all cells must have a valid row and column, table operations * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that From 793627c25bfe6c470605f1ffebde7b648b7a080f Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 18:13:22 +0000 Subject: [PATCH 06/23] docs: Update API reports --- packages/dds/tree/api-report/tree.alpha.api.md | 1 + packages/dds/tree/api-report/tree.beta.api.md | 1 + packages/dds/tree/api-report/tree.legacy.beta.api.md | 1 + .../fluid-framework/api-report/fluid-framework.alpha.api.md | 1 + .../fluid-framework/api-report/fluid-framework.beta.api.md | 1 + .../api-report/fluid-framework.legacy.beta.api.md | 1 + 6 files changed, 6 insertions(+) diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index 1ff8aa35e945..6751c5fa0e13 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -1227,6 +1227,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index 6f1972518b53..0873e9cad98d 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -594,6 +594,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index 9081f61547c2..08d447ea77fd 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -606,6 +606,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 2804b39c5ca5..42bdf24da48d 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -1605,6 +1605,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index d95fdeab9150..6b05f11a7ace 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -966,6 +966,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index 950128b24a91..dfabab278f85 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -1326,6 +1326,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; + // @system export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; From 0ced6ee07e232a5c7f115bf8da0ee21ed5a9c96b Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 13:08:22 -0800 Subject: [PATCH 07/23] docs: Update compat docs --- packages/dds/tree/src/tableSchema.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 9a9df2e8681e..85849363b758 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -1343,11 +1343,17 @@ function removeRangeFromArray( * * @remarks * - * Note: The APIs produced by this module ensure various tabular data invariants are maintained that the raw, underlying tree structures do not. + * Note: the APIs produced by this module ensure various tabular data invariants are maintained that the raw, underlying tree structures do not. * For example, they ensure that cells always correspond to existing rows and columns (and do not become "orphaned" due to row/column deletion, etc.). * For this reason, direct manipulation of the underlying tree structures is not supported. * To modify the data, only the APIs provided here may be used. * + * Also note: these APIs leverage `SharedTree` functionality that was added in version {@link FluidClientVersion.v2_80 | 2.80.0}, + * which is not compatible with previous versions of this library. + * To ensure safe collaboration, you will need to configure the {@link @fluidframework/runtime-definitions#MinimumVersionForCollab} + * for the Fluid Runtime and/or `SharedTree` to at least `2.80.0`. + * To set this minimum version for `SharedTree`, use {@link configuredSharedTreeBeta}. + * * The primary APIs for create tabular data schema are: * * - {@link TableSchema.(table:1)} From 11fdf899b766a33df3faf02434693ff3f84ed621 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 13:32:19 -0800 Subject: [PATCH 08/23] docs: Add remarks about index keys --- packages/dds/tree/src/tableSchema.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 85849363b758..6ff051d338cd 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -1631,6 +1631,11 @@ export namespace TableSchema { /** * A key to uniquely identify a cell within a table. + * + * @remarks + * Note that edits to the table structure (including edits by collaborators) can cause indexes to refer to different cells over time. + * Therefore, it is recommended to use IDs or node references whenever possible to identify cells. + * * @input @beta */ export interface CellKey< From f6755958c09ff3ddb76a376d4ea02f162bca0976 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 13:49:02 -0800 Subject: [PATCH 09/23] docs: Add more index notes --- packages/dds/tree/src/tableSchema.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 6ff051d338cd..7601c2c61d63 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -1744,6 +1744,11 @@ export namespace TableSchema { getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; /** * Gets a table column by its index in the table. + * + * @remarks + * Note that edits to the table structure (including edits by collaborators) can cause indexes to refer to different columns over time. + * Therefore, it is recommended to use IDs whenever possible to identify columns. + * * @returns The column, if it exists. Otherwise, `undefined`. */ getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; @@ -1755,6 +1760,11 @@ export namespace TableSchema { getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; /** * Gets a table row by its index in the table. + * + * @remarks + * Note that edits to the table structure (including edits by collaborators) can cause indexes to refer to different rows over time. + * Therefore, it is recommended to use IDs whenever possible to identify rows. + * * @returns The row, if it exists. Otherwise, `undefined`. */ getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; From f75721da248ee5f90f14ab9cc1400b3de1a38558 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 13:59:44 -0800 Subject: [PATCH 10/23] feat(runtime-definitions): Promote `MinimumVersionForCollab` to beta --- .../api-extractor/api-extractor-lint-beta.cjs.json | 5 +++++ .../api-extractor/api-extractor-lint-beta.esm.json | 5 +++++ .../api-extractor/api-extractor.current.json | 2 +- .../api-report/runtime-definitions.beta.api.md | 3 +++ .../runtime-definitions.legacy.alpha.api.md | 2 +- .../runtime-definitions.legacy.beta.api.md | 2 +- packages/runtime/runtime-definitions/package.json | 12 ++++++++++++ .../src/compatibilityDefinitions.ts | 2 +- 8 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json create mode 100644 packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json diff --git a/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json new file mode 100644 index 000000000000..7af093bb825b --- /dev/null +++ b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.cjs.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "extends": "/../../../common/build/build-common/api-extractor-lint.entrypoint.json", + "mainEntryPointFilePath": "/dist/beta.d.ts" +} diff --git a/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json new file mode 100644 index 000000000000..82773789eaee --- /dev/null +++ b/packages/runtime/runtime-definitions/api-extractor/api-extractor-lint-beta.esm.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "extends": "/../../../common/build/build-common/api-extractor-lint.entrypoint.json", + "mainEntryPointFilePath": "/lib/beta.d.ts" +} diff --git a/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json b/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json index 6ae39a96d271..3b513b5dc87a 100644 --- a/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json +++ b/packages/runtime/runtime-definitions/api-extractor/api-extractor.current.json @@ -1,5 +1,5 @@ { "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", "extends": "/../../../common/build/build-common/api-extractor-report.esm.current.json", - "mainEntryPointFilePath": "/lib/public.d.ts" + "mainEntryPointFilePath": "/lib/beta.d.ts" } diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md index 58964cc8f162..d20a3e70d70d 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.beta.api.md @@ -4,6 +4,9 @@ ```ts +// @beta @input +export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`; + // (No @packageDocumentation comment for this package) ``` diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md index ea5818ca651d..7a370ae49d76 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.alpha.api.md @@ -397,7 +397,7 @@ export interface LocalAttributionKey { type: "local"; } -// @beta @legacy @input +// @beta @input export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`; // @beta @legacy diff --git a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md index 19c22eee4da3..c21343197b7a 100644 --- a/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md +++ b/packages/runtime/runtime-definitions/api-report/runtime-definitions.legacy.beta.api.md @@ -388,7 +388,7 @@ export interface LocalAttributionKey { type: "local"; } -// @beta @legacy @input +// @beta @input export type MinimumVersionForCollab = `${1 | 2}.${bigint}.${bigint}` | `${1 | 2}.${bigint}.${bigint}-${string}`; // @beta @legacy diff --git a/packages/runtime/runtime-definitions/package.json b/packages/runtime/runtime-definitions/package.json index c56d70b805a2..ed1dae57baa4 100644 --- a/packages/runtime/runtime-definitions/package.json +++ b/packages/runtime/runtime-definitions/package.json @@ -23,6 +23,16 @@ "default": "./dist/index.js" } }, + "./beta": { + "import": { + "types": "./lib/beta.d.ts", + "default": "./lib/index.js" + }, + "require": { + "types": "./dist/beta.d.ts", + "default": "./dist/index.js" + } + }, "./legacy": { "import": { "types": "./lib/legacy.d.ts", @@ -74,9 +84,11 @@ "check:biome": "biome check .", "check:exports": "concurrently \"npm:check:exports:*\"", "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json", + "check:exports:cjs:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.cjs.json", "check:exports:cjs:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.cjs.json", "check:exports:cjs:legacyAlpha": "api-extractor run --config api-extractor/api-extractor-lint-legacyAlpha.cjs.json", "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json", + "check:exports:esm:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.esm.json", "check:exports:esm:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.esm.json", "check:exports:esm:legacyAlpha": "api-extractor run --config api-extractor/api-extractor-lint-legacyAlpha.esm.json", "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json", diff --git a/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts b/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts index 85db85b85430..a8176b2ee323 100644 --- a/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts +++ b/packages/runtime/runtime-definitions/src/compatibilityDefinitions.ts @@ -26,7 +26,7 @@ * For example it might make sense to constrain this to something like `"1.4.0" | typeof defaultMinVersionForCollab | 2.${bigint}.0"`. * * @input - * @legacy @beta + * @beta */ export type MinimumVersionForCollab = | `${1 | 2}.${bigint}.${bigint}` From 7479cd8b9af7abe0d88c21556f46ea320aeacdb7 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:08:00 -0800 Subject: [PATCH 11/23] feat(tree): Promote `minVersionForCollab` option to beta --- .../dds/tree/api-report/tree.alpha.api.md | 10 +++++++--- packages/dds/tree/api-report/tree.beta.api.md | 7 ++++++- .../tree/api-report/tree.legacy.beta.api.md | 7 ++++++- packages/dds/tree/src/codec/codec.ts | 20 ++++++++++++------- packages/dds/tree/src/codec/index.ts | 1 + packages/dds/tree/src/index.ts | 1 + .../dds/tree/src/shared-tree/sharedTree.ts | 3 ++- .../api-report/fluid-framework.alpha.api.md | 10 +++++++--- .../api-report/fluid-framework.beta.api.md | 7 ++++++- .../fluid-framework.legacy.beta.api.md | 7 ++++++- 10 files changed, 55 insertions(+), 18 deletions(-) diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index 6751c5fa0e13..34401e6c54a9 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -158,12 +158,16 @@ export function cloneWithReplacements(root: unknown, rootKey: string, replacer: export type CodecName = string; // @alpha @input -export interface CodecWriteOptions extends ICodecOptions { +export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta { readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean; - readonly minVersionForCollab: MinimumVersionForCollab; readonly writeVersionOverrides?: ReadonlyMap; } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -1113,7 +1117,7 @@ export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial; // @alpha @sealed export interface SimpleAllowedTypeAttributes { diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index 0873e9cad98d..48cea53efd25 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -89,6 +89,11 @@ Kind // @beta export function asBeta(view: TreeView): TreeViewBeta; +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -562,7 +567,7 @@ export class SchemaUpgrade { type ScopedSchemaName = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; // @public @sealed @system export interface SimpleNodeSchemaBase { diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index 08d447ea77fd..e42e60cfec01 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -89,6 +89,11 @@ Kind // @beta export function asBeta(view: TreeView): TreeViewBeta; +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -574,7 +579,7 @@ export const SharedTreeAttributes: IChannelAttributes; export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree"; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; // @public @sealed @system export interface SimpleNodeSchemaBase { diff --git a/packages/dds/tree/src/codec/codec.ts b/packages/dds/tree/src/codec/codec.ts index a66fff889392..74423df2002c 100644 --- a/packages/dds/tree/src/codec/codec.ts +++ b/packages/dds/tree/src/codec/codec.ts @@ -137,12 +137,10 @@ export interface ICodecOptions { } /** - * Options relating to encoding of persisted data. - * @remarks - * Extends {@link ICodecOptions} with options that are specific to encoding data. - * @alpha @input + * Options relating to collaborative features. + * @input @beta */ -export interface CodecWriteOptions extends ICodecOptions { +export interface CodecWriteOptionsBeta { /** * The minimum version of the Fluid Framework client output must be encoded to be compatible with. * @remarks @@ -153,16 +151,24 @@ export interface CodecWriteOptions extends ICodecOptions { * the data's format should be versioned and if they can't handle the format they should error. */ readonly minVersionForCollab: MinimumVersionForCollab; +} +/** + * Options relating to encoding of persisted data. + * @remarks + * Extends {@link ICodecOptions} with options that are specific to encoding data. + * @alpha @input + */ +export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta { /** * Overrides the version of the codec to use for encoding. * @remarks - * Without an override, the selected version will be based on {@link CodecWriteOptions.minVersionForCollab}. + * Without an override, the selected version will be based on {@link CodecWriteOptionsBeta.minVersionForCollab}. */ readonly writeVersionOverrides?: ReadonlyMap; /** - * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptions.minVersionForCollab}. + * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptionsBeta.minVersionForCollab}. */ readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean; } diff --git a/packages/dds/tree/src/codec/index.ts b/packages/dds/tree/src/codec/index.ts index 30a494130c84..c4497a799539 100644 --- a/packages/dds/tree/src/codec/index.ts +++ b/packages/dds/tree/src/codec/index.ts @@ -10,6 +10,7 @@ export { type ICodecFamily, type ICodecOptions, type CodecWriteOptions, + type CodecWriteOptionsBeta, type IDecoder, type IEncoder, type IJsonCodec, diff --git a/packages/dds/tree/src/index.ts b/packages/dds/tree/src/index.ts index 8437b6e02a63..76e13250e8b6 100644 --- a/packages/dds/tree/src/index.ts +++ b/packages/dds/tree/src/index.ts @@ -319,6 +319,7 @@ export { persistedToSimpleSchema } from "./shared-tree/index.js"; export { type ICodecOptions, type CodecWriteOptions, + type CodecWriteOptionsBeta, FluidClientVersion, type FormatValidator, FormatValidatorNoOp, diff --git a/packages/dds/tree/src/shared-tree/sharedTree.ts b/packages/dds/tree/src/shared-tree/sharedTree.ts index b23df5e23beb..4e8826b53bf0 100644 --- a/packages/dds/tree/src/shared-tree/sharedTree.ts +++ b/packages/dds/tree/src/shared-tree/sharedTree.ts @@ -21,6 +21,7 @@ import { import { type CodecTree, type CodecWriteOptions, + type CodecWriteOptionsBeta, DependentFormatVersion, FluidClientVersion, FormatValidatorNoOp, @@ -631,7 +632,7 @@ export function getCodecTreeForSharedTreeFormat( * Configuration options for SharedTree. * @beta @input */ -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; /** * Configuration options for SharedTree with alpha features. diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 42bdf24da48d..21156db317d1 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -165,12 +165,16 @@ export function cloneWithReplacements(root: unknown, rootKey: string, replacer: export type CodecName = string; // @alpha @input -export interface CodecWriteOptions extends ICodecOptions { +export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta { readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean; - readonly minVersionForCollab: MinimumVersionForCollab; readonly writeVersionOverrides?: ReadonlyMap; } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -1491,7 +1495,7 @@ export interface SharedTreeOptions extends SharedTreeOptionsBeta, Partial; // @alpha @sealed export interface SimpleAllowedTypeAttributes { diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index 6b05f11a7ace..bba8e96b5b4a 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -96,6 +96,11 @@ export enum AttachState { Detached = "Detached" } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -934,7 +939,7 @@ export interface SharedObjectKind extends ErasedTyp export const SharedTree: SharedObjectKind; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; // @public @sealed @system export interface SimpleNodeSchemaBase { diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index dfabab278f85..27c172610d7f 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -96,6 +96,11 @@ export enum AttachState { Detached = "Detached" } +// @beta @input +export interface CodecWriteOptionsBeta { + readonly minVersionForCollab: MinimumVersionForCollab; +} + // @public export enum CommitKind { Default = 0, @@ -1292,7 +1297,7 @@ export type SharedStringSegment = TextSegment | Marker; export const SharedTree: SharedObjectKind; // @beta @input -export type SharedTreeOptionsBeta = ForestOptions; +export type SharedTreeOptionsBeta = ForestOptions & Partial; export { Side } From 9756690bcde9f111e6360b71262848ec86b4e3dc Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:10:17 -0800 Subject: [PATCH 12/23] docs: Add changeset --- .changeset/sickly-insects-whisper.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .changeset/sickly-insects-whisper.md diff --git a/.changeset/sickly-insects-whisper.md b/.changeset/sickly-insects-whisper.md new file mode 100644 index 000000000000..2d1d74bd2595 --- /dev/null +++ b/.changeset/sickly-insects-whisper.md @@ -0,0 +1,9 @@ +--- +"fluid-framework": minor +"@fluidframework/tree": minor +"__section": feature +--- +Promote TableSchema APIs to beta + +Promotes the `SharedTree` [TableSchema](https://fluidframework.com/docs/api/fluid-framework/tableschema-namespace) from alpha to beta. +These APIs can now be imported via `@fluidframework/tree/beta`. From 15b50176903e6cb53886a16e0fd892e06c6360cb Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:20:11 -0800 Subject: [PATCH 13/23] docs: Fix comment --- packages/dds/tree/src/codec/codec.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dds/tree/src/codec/codec.ts b/packages/dds/tree/src/codec/codec.ts index 74423df2002c..6575ff073cb9 100644 --- a/packages/dds/tree/src/codec/codec.ts +++ b/packages/dds/tree/src/codec/codec.ts @@ -137,7 +137,7 @@ export interface ICodecOptions { } /** - * Options relating to collaborative features. + * Options relating to encoding of persisted data. * @input @beta */ export interface CodecWriteOptionsBeta { From 057a16a2f8d6e5694cb6b66e4c13f9d718d6eb4f Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:27:01 -0800 Subject: [PATCH 14/23] revert: Table changes on this branch --- .../dds/tree/api-report/tree.alpha.api.md | 4 +- packages/dds/tree/api-report/tree.beta.api.md | 143 ------------------ .../tree/api-report/tree.legacy.beta.api.md | 143 ------------------ packages/dds/tree/src/tableSchema.ts | 76 ++++------ .../api-report/fluid-framework.alpha.api.md | 4 +- .../api-report/fluid-framework.beta.api.md | 143 ------------------ .../fluid-framework.legacy.beta.api.md | 143 ------------------ 7 files changed, 35 insertions(+), 621 deletions(-) diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index 34401e6c54a9..da70f490554a 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -1212,7 +1212,7 @@ export interface SnapshotFileSystem { }): void; } -// @beta @system +// @alpha @system export namespace System_TableSchema { // @sealed @system export type ColumnSchemaBase = ReturnType>; @@ -1358,7 +1358,7 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @beta +// @alpha export namespace TableSchema { // @input export interface CellKey { diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index 48cea53efd25..d6a1f4e43594 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -580,69 +580,6 @@ export function singletonSchema, true, Record, undefined>; -// @beta @system -export namespace System_TableSchema { - // @sealed @system - export type ColumnSchemaBase = ReturnType>; - // @system - export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - }>; - // @system - export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; - }>; - // @system - export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { - create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; - } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); - // @system - export type DefaultPropsType = ReturnType>; - // @system - export interface OptionsWithCellSchema { - readonly cell: TCellSchema; - } - // @system - export interface OptionsWithSchemaFactory { - readonly schemaFactory: TSchemaFactory; - } - // @system - export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { - moveToEnd(sourceIndex: number): void; - moveToStart(sourceIndex: number): void; - moveToIndex(sourceIndex: number, destinationIndex: number): void; - moveRangeToEnd(startIndex: number, endIndex: number): void; - moveRangeToStart(startIndex: number, endIndex: number): void; - moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; - }; - // @sealed @system - export type RowSchemaBase = ReturnType>; - // @system - export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @sealed @system - export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; -} - // @public @system export namespace System_Unsafe { // @system @@ -726,86 +663,6 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @beta -export namespace TableSchema { - // @input - export interface CellKey { - readonly column: string | number | TreeNodeFromImplicitAllowedTypes; - readonly row: string | number | TreeNodeFromImplicitAllowedTypes; - } - // @sealed - export interface Column { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.ColumnSchemaBase; - // @input - export interface InsertColumnsParameters { - readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; - readonly index?: number | undefined; - } - // @input - export interface InsertRowsParameters { - readonly index?: number | undefined; - readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; - } - // @sealed - export interface Row { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.RowSchemaBase; - // @input - export interface SetCellParameters { - readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; - readonly key: CellKey; - } - // @sealed - export interface Table, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns: System_TableSchema.RearrangeableList; - getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; - insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; - removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - readonly rows: System_TableSchema.RearrangeableList; - setCell(params: SetCellParameters): void; - } - export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - }): System_TableSchema.TableSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly row: TRow; - }): System_TableSchema.TableSchemaBase, TRow>; - export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - readonly row: TRow; - }): System_TableSchema.TableSchemaBase; - // @input - export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns?: Iterable> | undefined; - readonly rows?: Iterable> | undefined; - } -} - // @public export type TransactionConstraint = NodeInDocumentConstraint; diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index e42e60cfec01..1f62f7347745 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -592,69 +592,6 @@ export function singletonSchema, true, Record, undefined>; -// @beta @system -export namespace System_TableSchema { - // @sealed @system - export type ColumnSchemaBase = ReturnType>; - // @system - export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - }>; - // @system - export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; - }>; - // @system - export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { - create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; - } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); - // @system - export type DefaultPropsType = ReturnType>; - // @system - export interface OptionsWithCellSchema { - readonly cell: TCellSchema; - } - // @system - export interface OptionsWithSchemaFactory { - readonly schemaFactory: TSchemaFactory; - } - // @system - export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { - moveToEnd(sourceIndex: number): void; - moveToStart(sourceIndex: number): void; - moveToIndex(sourceIndex: number, destinationIndex: number): void; - moveRangeToEnd(startIndex: number, endIndex: number): void; - moveRangeToStart(startIndex: number, endIndex: number): void; - moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; - }; - // @sealed @system - export type RowSchemaBase = ReturnType>; - // @system - export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @sealed @system - export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; -} - // @public @system export namespace System_Unsafe { // @system @@ -738,86 +675,6 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @beta -export namespace TableSchema { - // @input - export interface CellKey { - readonly column: string | number | TreeNodeFromImplicitAllowedTypes; - readonly row: string | number | TreeNodeFromImplicitAllowedTypes; - } - // @sealed - export interface Column { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.ColumnSchemaBase; - // @input - export interface InsertColumnsParameters { - readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; - readonly index?: number | undefined; - } - // @input - export interface InsertRowsParameters { - readonly index?: number | undefined; - readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; - } - // @sealed - export interface Row { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.RowSchemaBase; - // @input - export interface SetCellParameters { - readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; - readonly key: CellKey; - } - // @sealed - export interface Table, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns: System_TableSchema.RearrangeableList; - getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; - insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; - removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - readonly rows: System_TableSchema.RearrangeableList; - setCell(params: SetCellParameters): void; - } - export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - }): System_TableSchema.TableSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly row: TRow; - }): System_TableSchema.TableSchemaBase, TRow>; - export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - readonly row: TRow; - }): System_TableSchema.TableSchemaBase; - // @input - export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns?: Iterable> | undefined; - readonly rows?: Iterable> | undefined; - } -} - // @public export type TransactionConstraint = NodeInDocumentConstraint; diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 7601c2c61d63..5ec40b41362c 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -96,7 +96,7 @@ export interface RowPrivate< * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that * guard transactions from producing orphaned cells. * - * @system @beta + * @system @alpha */ export namespace System_TableSchema { /** @@ -107,7 +107,7 @@ export namespace System_TableSchema { * Note: this can't reasonably be implemented via `Pick>` because we only want to include the * subset of its method overloads which do not support moving items between lists. * - * @beta @system + * @alpha @system */ export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { @@ -135,7 +135,7 @@ export namespace System_TableSchema { * Longer term, it would be better to simply omit "props" altogether by default. * For now, this ensures that the user doesn't have to specify a "props" entry when initializing column/row nodes * and ensures that they cannot set anything that might conflict with future evolutions of the schema. - * @system @beta + * @system @alpha */ export type DefaultPropsType = ReturnType>; @@ -143,7 +143,7 @@ export namespace System_TableSchema { * A base interface for factory input options which include an schema factory. * @remarks This interface should not be referenced directly. * @privateRemarks This interface primarily exists to provide a single home for property documentation. - * @system @beta + * @system @alpha */ export interface OptionsWithSchemaFactory { /** @@ -158,7 +158,7 @@ export namespace System_TableSchema { * A base interface for factory input options which include the table cell schema. * @remarks This interface should not be referenced directly. * @privateRemarks This interface primarily exists to provide a single home for property documentation. - * @system @beta + * @system @alpha */ export interface OptionsWithCellSchema { /** @@ -172,7 +172,7 @@ export namespace System_TableSchema { /** * Base options for creating table column schema. * @remarks Includes parameters common to all column factory overloads. - * @system @beta + * @system @alpha */ export type CreateColumnOptionsBase< TUserScope extends string = string, @@ -182,7 +182,7 @@ export namespace System_TableSchema { /** * Factory for creating column schema. - * @system @beta + * @system @alpha */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createColumnSchema< @@ -298,7 +298,7 @@ export namespace System_TableSchema { /** * Base column schema type. - * @sealed @system @beta + * @sealed @system @alpha */ export type ColumnSchemaBase< TUserScope extends string = string, @@ -313,7 +313,7 @@ export namespace System_TableSchema { /** * Base options for creating table row schema. * @remarks Includes parameters common to all row factory overloads. - * @system @beta + * @system @alpha */ export type CreateRowOptionsBase< TUserScope extends string = string, @@ -323,7 +323,7 @@ export namespace System_TableSchema { /** * Factory for creating row schema. - * @system @beta + * @system @alpha */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createRowSchema< @@ -451,7 +451,7 @@ export namespace System_TableSchema { /** * Base row schema type. - * @sealed @system @beta + * @sealed @system @alpha */ export type RowSchemaBase< TUserScope extends string = string, @@ -466,7 +466,7 @@ export namespace System_TableSchema { /** * Base options for creating table schema. * @remarks Includes parameters common to all table factory overloads. - * @system @beta + * @system @alpha */ export type TableFactoryOptionsBase< TUserScope extends string = string, @@ -476,7 +476,7 @@ export namespace System_TableSchema { /** * Factory for creating table schema. - * @system @beta + * @system @alpha */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createTableSchema< @@ -1297,7 +1297,7 @@ export namespace System_TableSchema { /** * Base row schema type. - * @sealed @system @beta + * @sealed @system @alpha */ export type TableSchemaBase< TUserScope extends string, @@ -1450,7 +1450,7 @@ function removeRangeFromArray( * The above examples are backed by tests in `tableSchema.spec.ts`. * Those tests and these examples should be kept in-sync to ensure that the examples are correct. * - * @beta + * @alpha */ export namespace TableSchema { // #region Column @@ -1460,7 +1460,7 @@ export namespace TableSchema { * @remarks Implemented by the schema class returned from {@link TableSchema.(column:2)}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the column. - * @sealed @beta + * @sealed @alpha */ export interface Column< // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reserving this for future use. @@ -1488,7 +1488,7 @@ export namespace TableSchema { * Factory for creating new table column schema. * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. - * @beta + * @alpha */ export function column< const TUserScope extends string, @@ -1509,7 +1509,7 @@ export namespace TableSchema { * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the column. - * @beta + * @alpha */ export function column< const TUserScope extends string, @@ -1549,7 +1549,7 @@ export namespace TableSchema { * @remarks Implemented by the schema class returned from {@link TableSchema.(row:2)}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the row. - * @sealed @beta + * @sealed @alpha */ export interface Row< // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reserving this for future use. @@ -1577,7 +1577,7 @@ export namespace TableSchema { * Factory for creating new table column schema. * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. - * @beta + * @alpha */ export function row< const TUserScope extends string, @@ -1594,7 +1594,7 @@ export namespace TableSchema { * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}. * @typeParam TProps - Additional properties to associate with the row. - * @beta + * @alpha */ export function row< const TUserScope extends string, @@ -1632,11 +1632,7 @@ export namespace TableSchema { /** * A key to uniquely identify a cell within a table. * - * @remarks - * Note that edits to the table structure (including edits by collaborators) can cause indexes to refer to different cells over time. - * Therefore, it is recommended to use IDs or node references whenever possible to identify cells. - * - * @input @beta + * @input @alpha */ export interface CellKey< TColumn extends ImplicitAllowedTypes, @@ -1655,7 +1651,7 @@ export namespace TableSchema { /** * {@link TableSchema.Table.insertColumns} parameters. - * @input @beta + * @input @alpha */ export interface InsertColumnsParameters { /** @@ -1672,7 +1668,7 @@ export namespace TableSchema { /** * {@link TableSchema.Table.insertRows} parameters. - * @input @beta + * @input @alpha */ export interface InsertRowsParameters { /** @@ -1689,7 +1685,7 @@ export namespace TableSchema { /** * {@link TableSchema.Table.setCell} parameters. - * @input @beta + * @input @alpha */ export interface SetCellParameters< TCell extends ImplicitAllowedTypes, @@ -1719,7 +1715,7 @@ export namespace TableSchema { * @typeParam TColumn - The type of the columns in the table. * @typeParam TRow - The type of the rows in the table. * - * @sealed @beta + * @sealed @alpha */ export interface Table< TUserScope extends string, @@ -1744,11 +1740,6 @@ export namespace TableSchema { getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; /** * Gets a table column by its index in the table. - * - * @remarks - * Note that edits to the table structure (including edits by collaborators) can cause indexes to refer to different columns over time. - * Therefore, it is recommended to use IDs whenever possible to identify columns. - * * @returns The column, if it exists. Otherwise, `undefined`. */ getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; @@ -1760,11 +1751,6 @@ export namespace TableSchema { getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; /** * Gets a table row by its index in the table. - * - * @remarks - * Note that edits to the table structure (including edits by collaborators) can cause indexes to refer to different rows over time. - * Therefore, it is recommended to use IDs whenever possible to identify rows. - * * @returns The row, if it exists. Otherwise, `undefined`. */ getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; @@ -1895,7 +1881,7 @@ export namespace TableSchema { /** * Input parameters for {@link TableSchema.Table}'s `create` factory method. - * @input @beta + * @input @alpha */ export interface TableFactoryMethodParameters< TUserScope extends string, @@ -1922,7 +1908,7 @@ export namespace TableSchema { * @typeParam TUserScope - The {@link SchemaFactory.scope | schema factory scope}. * The resulting schema will have an identifier of the form: `com.fluidframework.table<${TUserScope}>.Table`. * @typeParam TCell - The type of the cells in the table. - * @beta + * @alpha */ export function table< const TUserScope extends string, @@ -1949,7 +1935,7 @@ export namespace TableSchema { * The resulting schema will have an identifier of the form: `com.fluidframework.table<${TUserScope}>.Table`. * @typeParam TCell - The type of the cells in the table. * @typeParam TColumn - The type of the columns in the table. - * @beta + * @alpha */ export function table< const TUserScope extends string, @@ -1975,7 +1961,7 @@ export namespace TableSchema { * The resulting schema will have an identifier of the form: `com.fluidframework.table<${TUserScope}>.Table`. * @typeParam TCell - The type of the cells in the table. * @typeParam TRow - The type of the rows in the table. - * @beta + * @alpha */ export function table< const TUserScope extends string, @@ -2006,7 +1992,7 @@ export namespace TableSchema { * @typeParam TCell - The type of the cells in the table. * @typeParam TColumn - The type of the columns in the table. * @typeParam TRow - The type of the rows in the table. - * @beta + * @alpha */ export function table< const TUserScope extends string, diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 21156db317d1..4eabee6c12b3 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -1590,7 +1590,7 @@ export interface SnapshotFileSystem { }): void; } -// @beta @system +// @alpha @system export namespace System_TableSchema { // @sealed @system export type ColumnSchemaBase = ReturnType>; @@ -1736,7 +1736,7 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @beta +// @alpha export namespace TableSchema { // @input export interface CellKey { diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index bba8e96b5b4a..8f1ecfe7e114 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -952,69 +952,6 @@ export function singletonSchema, true, Record, undefined>; -// @beta @system -export namespace System_TableSchema { - // @sealed @system - export type ColumnSchemaBase = ReturnType>; - // @system - export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - }>; - // @system - export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; - }>; - // @system - export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { - create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; - } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); - // @system - export type DefaultPropsType = ReturnType>; - // @system - export interface OptionsWithCellSchema { - readonly cell: TCellSchema; - } - // @system - export interface OptionsWithSchemaFactory { - readonly schemaFactory: TSchemaFactory; - } - // @system - export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { - moveToEnd(sourceIndex: number): void; - moveToStart(sourceIndex: number): void; - moveToIndex(sourceIndex: number, destinationIndex: number): void; - moveRangeToEnd(startIndex: number, endIndex: number): void; - moveRangeToStart(startIndex: number, endIndex: number): void; - moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; - }; - // @sealed @system - export type RowSchemaBase = ReturnType>; - // @system - export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @sealed @system - export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; -} - // @public @system export namespace System_Unsafe { // @system @@ -1098,86 +1035,6 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @beta -export namespace TableSchema { - // @input - export interface CellKey { - readonly column: string | number | TreeNodeFromImplicitAllowedTypes; - readonly row: string | number | TreeNodeFromImplicitAllowedTypes; - } - // @sealed - export interface Column { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.ColumnSchemaBase; - // @input - export interface InsertColumnsParameters { - readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; - readonly index?: number | undefined; - } - // @input - export interface InsertRowsParameters { - readonly index?: number | undefined; - readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; - } - // @sealed - export interface Row { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.RowSchemaBase; - // @input - export interface SetCellParameters { - readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; - readonly key: CellKey; - } - // @sealed - export interface Table, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns: System_TableSchema.RearrangeableList; - getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; - insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; - removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - readonly rows: System_TableSchema.RearrangeableList; - setCell(params: SetCellParameters): void; - } - export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - }): System_TableSchema.TableSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly row: TRow; - }): System_TableSchema.TableSchemaBase, TRow>; - export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - readonly row: TRow; - }): System_TableSchema.TableSchemaBase; - // @input - export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns?: Iterable> | undefined; - readonly rows?: Iterable> | undefined; - } -} - // @public export interface Tagged { // (undocumented) diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index 27c172610d7f..4af1bf159aa8 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -1312,69 +1312,6 @@ export function singletonSchema, true, Record, undefined>; -// @beta @system -export namespace System_TableSchema { - // @sealed @system - export type ColumnSchemaBase = ReturnType>; - // @system - export type CreateColumnOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createColumnSchema(inputSchemaFactory: SchemaFactoryBeta, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Column">, NodeKind.Object, TreeNode & TableSchema.Column & WithType`, "Column">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - }>; - // @system - export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system - export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { - readonly id?: string | undefined; - readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; - } & (FieldHasDefault extends true ? { - props?: InsertableTreeFieldFromImplicitField | undefined; - } : { - props: InsertableTreeFieldFromImplicitField; - }), true, { - readonly props: TPropsSchema; - readonly id: FieldSchema_2, unknown>; - readonly cells: FieldSchema_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>, unknown>; - }>; - // @system - export function createTableSchema, const TRowSchema extends RowSchemaBase>(inputSchemaFactory: SchemaFactoryBeta, _cellSchema: TCellSchema, columnSchema: TColumnSchema, rowSchema: TRowSchema): { - create TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>>(this: TThis, initialContents?: TableSchema.TableFactoryMethodParameters | undefined): InstanceType; - } & (new (data?: InternalTreeNode | undefined) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown>) & TreeNodeSchemaCore`, "TableRoot"> & string, NodeKind, false, unknown, never, unknown> & (new (data: InternalTreeNode) => TreeNode & TableSchema.Table & WithType`, "TableRoot">, NodeKind, unknown> & WithType`, "TableRoot"> & string, NodeKind, unknown>); - // @system - export type DefaultPropsType = ReturnType>; - // @system - export interface OptionsWithCellSchema { - readonly cell: TCellSchema; - } - // @system - export interface OptionsWithSchemaFactory { - readonly schemaFactory: TSchemaFactory; - } - // @system - export type RearrangeableList = TreeNode & readonly TreeNodeFromImplicitAllowedTypes[] & { - moveToEnd(sourceIndex: number): void; - moveToStart(sourceIndex: number): void; - moveToIndex(sourceIndex: number, destinationIndex: number): void; - moveRangeToEnd(startIndex: number, endIndex: number): void; - moveRangeToStart(startIndex: number, endIndex: number): void; - moveRangeToIndex(startIndex: number, endIndex: number, destinationIndex: number): void; - }; - // @sealed @system - export type RowSchemaBase = ReturnType>; - // @system - export type TableFactoryOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @sealed @system - export type TableSchemaBase, TRowSchema extends RowSchemaBase> = ReturnType>; -} - // @public @system export namespace System_Unsafe { // @system @@ -1458,86 +1395,6 @@ export namespace System_Unsafe { export type TreeObjectNodeUnsafe, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe & WithType; } -// @beta -export namespace TableSchema { - // @input - export interface CellKey { - readonly column: string | number | TreeNodeFromImplicitAllowedTypes; - readonly row: string | number | TreeNodeFromImplicitAllowedTypes; - } - // @sealed - export interface Column { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell>): System_TableSchema.ColumnSchemaBase; - export function column(params: System_TableSchema.CreateColumnOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.ColumnSchemaBase; - // @input - export interface InsertColumnsParameters { - readonly columns: InsertableTreeNodeFromImplicitAllowedTypes[]; - readonly index?: number | undefined; - } - // @input - export interface InsertRowsParameters { - readonly index?: number | undefined; - readonly rows: InsertableTreeNodeFromImplicitAllowedTypes[]; - } - // @sealed - export interface Row { - readonly id: string; - get props(): TreeFieldFromImplicitField; - set props(value: InsertableTreeFieldFromImplicitField); - } - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell>): System_TableSchema.RowSchemaBase; - export function row(params: System_TableSchema.CreateRowOptionsBase, TCell> & { - readonly props: TProps; - }): System_TableSchema.RowSchemaBase; - // @input - export interface SetCellParameters { - readonly cell: InsertableTreeNodeFromImplicitAllowedTypes; - readonly key: CellKey; - } - // @sealed - export interface Table, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns: System_TableSchema.RearrangeableList; - getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getColumn(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(id: string): TreeNodeFromImplicitAllowedTypes | undefined; - getRow(index: number): TreeNodeFromImplicitAllowedTypes | undefined; - insertColumns(params: InsertColumnsParameters): TreeNodeFromImplicitAllowedTypes[]; - insertRows(params: InsertRowsParameters): TreeNodeFromImplicitAllowedTypes[]; - removeCell(key: CellKey): TreeNodeFromImplicitAllowedTypes | undefined; - removeColumns(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(index?: number | undefined, count?: number | undefined): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly TreeNodeFromImplicitAllowedTypes[]): TreeNodeFromImplicitAllowedTypes[]; - removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes[]; - readonly rows: System_TableSchema.RearrangeableList; - setCell(params: SetCellParameters): void; - } - export function table(params: System_TableSchema.TableFactoryOptionsBase, TCell>): System_TableSchema.TableSchemaBase, System_TableSchema.RowSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - }): System_TableSchema.TableSchemaBase>; - export function table>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly row: TRow; - }): System_TableSchema.TableSchemaBase, TRow>; - export function table, const TRow extends System_TableSchema.RowSchemaBase>(params: System_TableSchema.TableFactoryOptionsBase, TCell> & { - readonly column: TColumn; - readonly row: TRow; - }): System_TableSchema.TableSchemaBase; - // @input - export interface TableFactoryMethodParameters, TRow extends System_TableSchema.RowSchemaBase> { - readonly columns?: Iterable> | undefined; - readonly rows?: Iterable> | undefined; - } -} - // @public export interface Tagged { // (undocumented) From a52aca52746cda8204a129409b96e2f34bd1a2bd Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:38:59 -0800 Subject: [PATCH 15/23] docs: Update changesets and promote another API --- .changeset/gross-apples-defend.md | 21 +++++++++++++++++++ .changeset/sickly-insects-whisper.md | 9 -------- .../dds/tree/api-report/tree.alpha.api.md | 2 +- packages/dds/tree/api-report/tree.beta.api.md | 10 +++++++++ .../tree/api-report/tree.legacy.beta.api.md | 10 +++++++++ packages/dds/tree/src/codec/codec.ts | 2 +- .../api-report/fluid-framework.alpha.api.md | 2 +- .../api-report/fluid-framework.beta.api.md | 10 +++++++++ .../fluid-framework.legacy.beta.api.md | 10 +++++++++ 9 files changed, 64 insertions(+), 12 deletions(-) create mode 100644 .changeset/gross-apples-defend.md delete mode 100644 .changeset/sickly-insects-whisper.md diff --git a/.changeset/gross-apples-defend.md b/.changeset/gross-apples-defend.md new file mode 100644 index 000000000000..9c71fc989838 --- /dev/null +++ b/.changeset/gross-apples-defend.md @@ -0,0 +1,21 @@ +--- +"fluid-framework": minor +"@fluidframework/tree": minor +"__section": feature +--- +Promote MinimumVersionForCollab to beta + +Promotes the [MinumumVersionForCollab](https://fluidframework.com/docs/api/runtime-definitions/minimumversionforcollab-typealias) type to beta, and adds option to [configuredSharedTreeBeta](https://fluidframework.com/docs/api/fluid-framework#configuredsharedtreebeta-function) for specifying it when creating a new `SharedTree`. + +This allows users to opt into new features and optimizations that are only available when certain minimum version thresholds are guaranteed. +For more details, see [FluidClientVersion](https://fluidframework.com/docs/api/fluid-framework#fluidclientversion-variable) + +#### Example usage + +```typescript +// Configure SharedTree DDS to ensure all clients must be on at least version `2.80.0` in order to collaborate. +// Edits made to this DDS by a client on an earlier version will fail, preventing potential document corruption. +const SharedTree = configuredSharedTreeBeta({ + minVersionForCollab: FluidClientVersion.v2_80, +}); +``` diff --git a/.changeset/sickly-insects-whisper.md b/.changeset/sickly-insects-whisper.md deleted file mode 100644 index 2d1d74bd2595..000000000000 --- a/.changeset/sickly-insects-whisper.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -"fluid-framework": minor -"@fluidframework/tree": minor -"__section": feature ---- -Promote TableSchema APIs to beta - -Promotes the `SharedTree` [TableSchema](https://fluidframework.com/docs/api/fluid-framework/tableschema-namespace) from alpha to beta. -These APIs can now be imported via `@fluidframework/tree/beta`. diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index da70f490554a..7e73a1a6baa7 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -364,7 +364,7 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @alpha +// @beta export const FluidClientVersion: { readonly v2_0: "2.0.0"; readonly v2_43: "2.43.0"; diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index d6a1f4e43594..8fd2a27c725e 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -190,6 +190,16 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; +// @beta +export const FluidClientVersion: { + readonly v2_0: "2.0.0"; + readonly v2_43: "2.43.0"; + readonly v2_52: "2.52.0"; + readonly v2_73: "2.73.0"; + readonly v2_74: "2.74.0"; + readonly v2_80: "2.80.0"; +}; + // @beta export namespace FluidSerializableAsTree { // @sealed diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index 1f62f7347745..e8f06e700d42 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -193,6 +193,16 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; +// @beta +export const FluidClientVersion: { + readonly v2_0: "2.0.0"; + readonly v2_43: "2.43.0"; + readonly v2_52: "2.52.0"; + readonly v2_73: "2.73.0"; + readonly v2_74: "2.74.0"; + readonly v2_80: "2.80.0"; +}; + // @beta export namespace FluidSerializableAsTree { // @sealed diff --git a/packages/dds/tree/src/codec/codec.ts b/packages/dds/tree/src/codec/codec.ts index 6575ff073cb9..d873bc09f9e5 100644 --- a/packages/dds/tree/src/codec/codec.ts +++ b/packages/dds/tree/src/codec/codec.ts @@ -536,7 +536,7 @@ export function withSchemaValidation< * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema. * TODO: compatibility requirements for how this enum can and cannot be changed should be clarified when/if it's used across multiple layers in the stack. * For example, if needed, would adding more leading zeros to the minor version break things. - * @alpha + * @beta */ export const FluidClientVersion = { /** diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 4eabee6c12b3..740a3b81c147 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -418,7 +418,7 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @alpha +// @beta export const FluidClientVersion: { readonly v2_0: "2.0.0"; readonly v2_43: "2.43.0"; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index 8f1ecfe7e114..1093b52a7a18 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -241,6 +241,16 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; +// @beta +export const FluidClientVersion: { + readonly v2_0: "2.0.0"; + readonly v2_43: "2.43.0"; + readonly v2_52: "2.52.0"; + readonly v2_73: "2.73.0"; + readonly v2_74: "2.74.0"; + readonly v2_80: "2.80.0"; +}; + // @public export type FluidObject = { [P in FluidObjectProviderKeys]?: T[P]; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index 4af1bf159aa8..34a2cb317cee 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -244,6 +244,16 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; +// @beta +export const FluidClientVersion: { + readonly v2_0: "2.0.0"; + readonly v2_43: "2.43.0"; + readonly v2_52: "2.52.0"; + readonly v2_73: "2.73.0"; + readonly v2_74: "2.74.0"; + readonly v2_80: "2.80.0"; +}; + // @public export type FluidObject = { [P in FluidObjectProviderKeys]?: T[P]; From f55889fb836210dbbadeee35f9cffc27cb619e17 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:44:50 -0800 Subject: [PATCH 16/23] revert: Tag change --- packages/dds/tree/api-report/tree.alpha.api.md | 2 +- packages/dds/tree/src/tableSchema.ts | 2 +- .../fluid-framework/api-report/fluid-framework.alpha.api.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index 7e73a1a6baa7..ea9488867ab3 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -1231,7 +1231,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system + // @sealed export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 5ec40b41362c..25dcc76bd524 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -323,7 +323,7 @@ export namespace System_TableSchema { /** * Factory for creating row schema. - * @system @alpha + * @sealed @alpha */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify export function createRowSchema< diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index 740a3b81c147..ba1ce20e203f 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -1609,7 +1609,7 @@ export namespace System_TableSchema { }>; // @system export type CreateRowOptionsBase = SchemaFactoryBeta, TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> = OptionsWithSchemaFactory & OptionsWithCellSchema; - // @system + // @sealed export function createRowSchema(inputSchemaFactory: SchemaFactoryBeta, cellSchema: TCellSchema, propsSchema: TPropsSchema): TreeNodeSchemaClass`, "Row">, NodeKind.Object, TreeNode & TableSchema.Row & WithType`, "Row">, NodeKind, unknown>, object & { readonly id?: string | undefined; readonly cells: (InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>> | undefined) & InsertableTypedNode_2`, "Row.cells">, NodeKind.Record, TreeRecordNode & WithType`, "Row.cells">, NodeKind.Record, unknown>, RecordNodeInsertableData_2, true, TCellSchema, undefined, unknown>>; From f1473566f056dd528f77f2b609fa4889f615219b Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 14:46:36 -0800 Subject: [PATCH 17/23] docs: Revert table schema docs changes --- packages/dds/tree/src/tableSchema.ts | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 25dcc76bd524..51ce49dd95c3 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -1343,16 +1343,10 @@ function removeRangeFromArray( * * @remarks * - * Note: the APIs produced by this module ensure various tabular data invariants are maintained that the raw, underlying tree structures do not. - * For example, they ensure that cells always correspond to existing rows and columns (and do not become "orphaned" due to row/column deletion, etc.). - * For this reason, direct manipulation of the underlying tree structures is not supported. - * To modify the data, only the APIs provided here may be used. - * - * Also note: these APIs leverage `SharedTree` functionality that was added in version {@link FluidClientVersion.v2_80 | 2.80.0}, - * which is not compatible with previous versions of this library. - * To ensure safe collaboration, you will need to configure the {@link @fluidframework/runtime-definitions#MinimumVersionForCollab} - * for the Fluid Runtime and/or `SharedTree` to at least `2.80.0`. - * To set this minimum version for `SharedTree`, use {@link configuredSharedTreeBeta}. + * WARNING: These APIs are in preview and are subject to change. + * Until these APIs have stabilized, it is not recommended to use them in production code. + * There may be breaking changes to these APIs and their underlying data format. + * Using these APIs in production code may result in data loss or corruption. * * The primary APIs for create tabular data schema are: * @@ -1375,6 +1369,11 @@ function removeRangeFromArray( * Column and Row schema created using these APIs are extensible via the `props` field. * This allows association of additional properties with column and row nodes. * + * There is a concept of cells in the table becoming "orphaned.". An orphaned cell is a cell that does not correspond to a valid row and column. + * In order to preserve the invariant that all cells must have a valid row and column, table operations + * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that + * guards transactions from producing orphaned cells. + * * @example Defining a Table schema * * ```typescript From 9846b9300b440eb28202ee96764fb8a07671ee8d Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 14:47:03 -0800 Subject: [PATCH 18/23] docs: Revert table schema docs changes --- packages/dds/tree/src/tableSchema.ts | 7 ------- 1 file changed, 7 deletions(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 51ce49dd95c3..1bd48ff14259 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -89,13 +89,6 @@ export interface RowPrivate< * This namespace should be strictly type-exported by the package. * All members should be tagged with `@system`. * - * Orphaned Cells: - * Without safeguards, it is possible for cells to become "orphaned". - * An orphaned cell is a cell that does not correspond to a valid row and column. - * In order to preserve the invariant that all cells must have a valid row and column, table operations - * (eg, inserting/removing rows/columns, or setting/removing a cell) will automatically include constraints that - * guard transactions from producing orphaned cells. - * * @system @alpha */ export namespace System_TableSchema { From cc62a2ca2d54da6dd280ecbde2199d8584f0c89c Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 14:47:17 -0800 Subject: [PATCH 19/23] docs: Fix typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- packages/dds/tree/src/tableSchema.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/dds/tree/src/tableSchema.ts b/packages/dds/tree/src/tableSchema.ts index 1bd48ff14259..46baf552dbee 100644 --- a/packages/dds/tree/src/tableSchema.ts +++ b/packages/dds/tree/src/tableSchema.ts @@ -1623,7 +1623,6 @@ export namespace TableSchema { /** * A key to uniquely identify a cell within a table. - * * @input @alpha */ export interface CellKey< From 07fd411f7f633bb8afd731050b10718347f6008a Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 14:49:48 -0800 Subject: [PATCH 20/23] docs: Update README --- packages/runtime/runtime-definitions/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/runtime/runtime-definitions/README.md b/packages/runtime/runtime-definitions/README.md index 38204b9076cf..3cd5ae854cfb 100644 --- a/packages/runtime/runtime-definitions/README.md +++ b/packages/runtime/runtime-definitions/README.md @@ -30,6 +30,8 @@ For more information on the related support guarantees, see [API Support Levels] To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/runtime-definitions` like normal. +To access the `beta` APIs, import via `@fluidframework/runtime-definitions/beta`. + To access the `legacy` APIs, import via `@fluidframework/runtime-definitions/legacy`. ## API Documentation From 28c27a9940308c9631ac7917407457d617e3ff4d Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Mon, 2 Feb 2026 16:15:26 -0800 Subject: [PATCH 21/23] docs: Update comment Co-authored-by: Craig Macomber (Microsoft) <42876482+CraigMacomber@users.noreply.github.com> --- .changeset/gross-apples-defend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/gross-apples-defend.md b/.changeset/gross-apples-defend.md index 9c71fc989838..13e2e28a6156 100644 --- a/.changeset/gross-apples-defend.md +++ b/.changeset/gross-apples-defend.md @@ -14,7 +14,7 @@ For more details, see [FluidClientVersion](https://fluidframework.com/docs/api/f ```typescript // Configure SharedTree DDS to ensure all clients must be on at least version `2.80.0` in order to collaborate. -// Edits made to this DDS by a client on an earlier version will fail, preventing potential document corruption. +// Edits made to this DDS by this client might cause clients older than the specified version to be unable to open the document and/or error out of collaboration sessions. const SharedTree = configuredSharedTreeBeta({ minVersionForCollab: FluidClientVersion.v2_80, }); From bbfa89c59fe37664c3e9b85e23769ee016d84765 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 16:43:06 -0800 Subject: [PATCH 22/23] docs: Update changeset --- .changeset/gross-apples-defend.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/gross-apples-defend.md b/.changeset/gross-apples-defend.md index 13e2e28a6156..dbb90835c7dc 100644 --- a/.changeset/gross-apples-defend.md +++ b/.changeset/gross-apples-defend.md @@ -5,7 +5,7 @@ --- Promote MinimumVersionForCollab to beta -Promotes the [MinumumVersionForCollab](https://fluidframework.com/docs/api/runtime-definitions/minimumversionforcollab-typealias) type to beta, and adds option to [configuredSharedTreeBeta](https://fluidframework.com/docs/api/fluid-framework#configuredsharedtreebeta-function) for specifying it when creating a new `SharedTree`. +Promotes the [MinimumVersionForCollab](https://fluidframework.com/docs/api/runtime-definitions/minimumversionforcollab-typealias) type to beta, and adds option to [configuredSharedTreeBeta](https://fluidframework.com/docs/api/fluid-framework#configuredsharedtreebeta-function) for specifying it when creating a new `SharedTree`. This allows users to opt into new features and optimizations that are only available when certain minimum version thresholds are guaranteed. For more details, see [FluidClientVersion](https://fluidframework.com/docs/api/fluid-framework#fluidclientversion-variable) @@ -13,7 +13,7 @@ For more details, see [FluidClientVersion](https://fluidframework.com/docs/api/f #### Example usage ```typescript -// Configure SharedTree DDS to ensure all clients must be on at least version `2.80.0` in order to collaborate. +// Configure SharedTree DDS to limit the features it requires of collaborators and future document users to only those available in version `2.80.0` and later, overriding the `MinimumVersionForCollab` provided by the runtime (default: "2.0.0"). // Edits made to this DDS by this client might cause clients older than the specified version to be unable to open the document and/or error out of collaboration sessions. const SharedTree = configuredSharedTreeBeta({ minVersionForCollab: FluidClientVersion.v2_80, From e4e702ef806957dff650651ccb11ecd370d796f5 Mon Sep 17 00:00:00 2001 From: Josmithr Date: Mon, 2 Feb 2026 16:47:40 -0800 Subject: [PATCH 23/23] revert: Promotion of `FluidClientVersion` --- packages/dds/tree/api-report/tree.alpha.api.md | 2 +- packages/dds/tree/api-report/tree.beta.api.md | 10 ---------- packages/dds/tree/api-report/tree.legacy.beta.api.md | 10 ---------- packages/dds/tree/src/codec/codec.ts | 2 +- .../api-report/fluid-framework.alpha.api.md | 2 +- .../api-report/fluid-framework.beta.api.md | 10 ---------- .../api-report/fluid-framework.legacy.beta.api.md | 10 ---------- 7 files changed, 3 insertions(+), 43 deletions(-) diff --git a/packages/dds/tree/api-report/tree.alpha.api.md b/packages/dds/tree/api-report/tree.alpha.api.md index ea9488867ab3..c4c18b210b72 100644 --- a/packages/dds/tree/api-report/tree.alpha.api.md +++ b/packages/dds/tree/api-report/tree.alpha.api.md @@ -364,7 +364,7 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @beta +// @alpha export const FluidClientVersion: { readonly v2_0: "2.0.0"; readonly v2_43: "2.43.0"; diff --git a/packages/dds/tree/api-report/tree.beta.api.md b/packages/dds/tree/api-report/tree.beta.api.md index 8fd2a27c725e..d6a1f4e43594 100644 --- a/packages/dds/tree/api-report/tree.beta.api.md +++ b/packages/dds/tree/api-report/tree.beta.api.md @@ -190,16 +190,6 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @beta -export const FluidClientVersion: { - readonly v2_0: "2.0.0"; - readonly v2_43: "2.43.0"; - readonly v2_52: "2.52.0"; - readonly v2_73: "2.73.0"; - readonly v2_74: "2.74.0"; - readonly v2_80: "2.80.0"; -}; - // @beta export namespace FluidSerializableAsTree { // @sealed diff --git a/packages/dds/tree/api-report/tree.legacy.beta.api.md b/packages/dds/tree/api-report/tree.legacy.beta.api.md index e8f06e700d42..1f62f7347745 100644 --- a/packages/dds/tree/api-report/tree.legacy.beta.api.md +++ b/packages/dds/tree/api-report/tree.legacy.beta.api.md @@ -193,16 +193,6 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @beta -export const FluidClientVersion: { - readonly v2_0: "2.0.0"; - readonly v2_43: "2.43.0"; - readonly v2_52: "2.52.0"; - readonly v2_73: "2.73.0"; - readonly v2_74: "2.74.0"; - readonly v2_80: "2.80.0"; -}; - // @beta export namespace FluidSerializableAsTree { // @sealed diff --git a/packages/dds/tree/src/codec/codec.ts b/packages/dds/tree/src/codec/codec.ts index d873bc09f9e5..6575ff073cb9 100644 --- a/packages/dds/tree/src/codec/codec.ts +++ b/packages/dds/tree/src/codec/codec.ts @@ -536,7 +536,7 @@ export function withSchemaValidation< * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema. * TODO: compatibility requirements for how this enum can and cannot be changed should be clarified when/if it's used across multiple layers in the stack. * For example, if needed, would adding more leading zeros to the minor version break things. - * @beta + * @alpha */ export const FluidClientVersion = { /** diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md index ba1ce20e203f..a36c7caccf64 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md @@ -418,7 +418,7 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @beta +// @alpha export const FluidClientVersion: { readonly v2_0: "2.0.0"; readonly v2_43: "2.43.0"; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md index 1093b52a7a18..8f1ecfe7e114 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md @@ -241,16 +241,6 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @beta -export const FluidClientVersion: { - readonly v2_0: "2.0.0"; - readonly v2_43: "2.43.0"; - readonly v2_52: "2.52.0"; - readonly v2_73: "2.73.0"; - readonly v2_74: "2.74.0"; - readonly v2_80: "2.80.0"; -}; - // @public export type FluidObject = { [P in FluidObjectProviderKeys]?: T[P]; diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md index 34a2cb317cee..4af1bf159aa8 100644 --- a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md +++ b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md @@ -244,16 +244,6 @@ type FlexList = readonly LazyItem[]; // @public @system type FlexListToUnion = ExtractItemType; -// @beta -export const FluidClientVersion: { - readonly v2_0: "2.0.0"; - readonly v2_43: "2.43.0"; - readonly v2_52: "2.52.0"; - readonly v2_73: "2.73.0"; - readonly v2_74: "2.74.0"; - readonly v2_80: "2.80.0"; -}; - // @public export type FluidObject = { [P in FluidObjectProviderKeys]?: T[P];