@fluidframework/tree 2.33.1 → 2.40.0-336023

package/src/tableSchema.ts

@@ -7,6 +7,7 @@ import { oob } from "@fluidframework/core-utils/internal";
 
 import { Tree } from "./shared-tree/index.js";
 import {
+	type FieldHasDefault,
 	type ImplicitAllowedTypes,
 	type ImplicitFieldSchema,
 	type InsertableObjectFromSchemaRecord,
@@ -20,83 +21,176 @@ import {
 	type TreeNodeSchema,
 	type TreeNodeSchemaClass,
 	type WithType,
+	type TreeFieldFromImplicitField,
+	type InsertableTreeFieldFromImplicitField,
+	type InternalTreeNode,
+	type FieldSchema,
+	type FieldKind,
+	SchemaFactory,
+	type ImplicitAnnotatedFieldSchema,
+	type UnannotateImplicitFieldSchema,
 } from "./simple-tree/index.js";
 
 // Future improvement TODOs (ideally to be done before promoting these APIs to `@alpha`):
-// - Custom fields on Table/Row/Column (props pattern from Nick's demo)
-// - Overloads to make Column/Row schema optional when constructing Tables
 // - Record-like type parameters / input parameters?
-// - Move `@system` types into separate / sub scope?
+// - Omit `props` properties from Row and Column schemas when not provided?
+
+const tableSchemaFactorySubScope = "table";
 
 /**
- * Contains types and factories for creating schema to represent dynamic tabular data.
- * @privateRemarks TODO: document in more detail and add `@example`s.
- * @internal
+ * Not intended for use outside of this package.
+ *
+ * @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 @internal
  */
-export namespace TableSchema {
-	const tableSchemaFactorySubScope = "table";
-
-	// #region Column
-
+export namespace System_TableSchema {
 	/**
-	 * A column in a table.
-	 * @remarks Implemented by the schema class returned from {@link TableSchema.createColumn}.
-	 * @sealed @internal
+	 * 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 @internal
 	 */
-	export interface IColumn<TPropsSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes> {
+	export interface OptionsWithSchemaFactory<
+		TScope extends string | undefined = string | undefined,
+	> {
 		/**
-		 * The unique identifier of the column.
-		 * @remarks Uniquely identifies the node within the entire tree, not just the table.
+		 * Schema factory with which the Column schema will be associated.
+		 * @remarks Can be used to associate the resulting schema with an existing {@link SchemaFactory.scope|scope}.
 		 */
-		readonly id: string;
+		readonly schemaFactory: SchemaFactoryAlpha<TScope>;
+	}
 
+	/**
+	 * 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 @internal
+	 */
+	export interface OptionsWithCellSchema<
+		TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	> {
 		/**
-		 * User-provided column properties.
+		 * Schema for the table's cells.
 		 */
-		get props(): TreeNodeFromImplicitAllowedTypes<TPropsSchema>;
-		set props(value: InsertableTreeNodeFromImplicitAllowedTypes<TPropsSchema>);
+		readonly cell: TCellSchema;
 	}
 
+	// #region Column
+
+	/**
+	 * Base options for creating table cow schema.
+	 * @remarks Includes parameters common to all column factory overloads.
+	 * @system @internal
+	 */
+	export type CreateColumnOptionsBase<
+		TInputScope extends string | undefined = string | undefined,
+	> = OptionsWithSchemaFactory<TInputScope>;
+
 	/**
 	 * Factory for creating new table column schema.
-	 * @privateRemarks
-	 * TODO:
-	 * - Add overloads to make propsSchema optional.
-	 * - Take field schema rather than node schema for `propsSchema`, in particular to allow making
-	 * the additional properties optional.
-	 * @internal
+	 * @system @internal
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
-	export function createColumn<
+	export function createColumnInternal<
 		const TInputScope extends string | undefined,
-		const TPropsSchema extends ImplicitAllowedTypes,
+		const TPropsSchema extends ImplicitAnnotatedFieldSchema,
 	>(inputSchemaFactory: SchemaFactoryAlpha<TInputScope>, propsSchema: TPropsSchema) {
 		const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
 		type Scope = ScopedSchemaName<TInputScope, typeof tableSchemaFactorySubScope>;
 
+		// Note: `columnFields` is broken into two parts to work around a TypeScript bug
+		// that results in broken `.d.ts` output.
+		// See definition of `ColumnInsertableType` below.
+		const columnFieldsBuiltInParts = {
+			id: schemaFactory.identifier,
+		} as const;
+		const columnFieldsPropsPart = {
+			props: propsSchema,
+		} as const;
+
 		/**
 		 * {@link Column} fields.
-		 * @remarks Extracted for re-use in returned type signature defined later in this function.
+		 *
+		 * @remarks
+		 * Extracted for re-use in returned type signature defined later in this function.
 		 * The implicit typing is intentional.
+		 *
 		 * Note: ideally we would add a satisfies clause here to ensure that this satisfies
 		 * `Record<string, ImplicitFieldSchema>`, but doing so causes TypeScript to prematurely and incorrectly evaluate the type of `propsSchema`.
 		 * Likely related to the following issue: https://github.com/microsoft/TypeScript/issues/52394
 		 */
 		const columnFields = {
-			id: schemaFactory.identifier,
-			props: schemaFactory.required(propsSchema),
-		} as const;
+			...columnFieldsBuiltInParts,
+			...columnFieldsPropsPart,
+		} as const; // satisfies Record<string, ImplicitFieldSchema>;
 
 		/**
 		 * A column in a table.
 		 */
-		class Column extends schemaFactory.object("Column", columnFields) {}
+		class Column
+			extends schemaFactory.objectAlpha("Column", columnFields, {
+				// Will make it easier to evolve this schema in the future.
+				allowUnknownOptionalFields: true,
+			})
+			implements TableSchema.IColumn<TPropsSchema> {}
 
 		type ColumnValueType = TreeNode &
-			IColumn<TPropsSchema> &
+			TableSchema.IColumn<TPropsSchema> &
 			WithType<ScopedSchemaName<Scope, "Column">>;
 
-		type ColumnInsertableType = InsertableObjectFromSchemaRecord<typeof columnFields>;
+		// Note: ideally this type would just leverage `InsertableObjectFromSchemaRecord<typeof columnFields>`,
+		// but that results in broken `.d.ts` output due to a TypeScript bug.
+		// See: https://github.com/microsoft/TypeScript/issues/58688.
+		// Instead we extract and inline the typing of the "props" field here, which seems to sufficiently work around the issue.
+		// type ColumnInsertableType = InsertableObjectFromSchemaRecord<typeof columnFields>;
+		type ColumnInsertableType = InsertableObjectFromSchemaRecord<
+			typeof columnFieldsBuiltInParts
+		> &
+			(FieldHasDefault<UnannotateImplicitFieldSchema<TPropsSchema>> extends true
+				? // Note: The docs on the below properties are copied from `IRow.props`' docs to ensure that the
+					// documentation appears in the data insertion scenario.
+					// The contents are duplicated instead of using `@inheritdoc`, as intellisense does not correctly
+					// support `@inheritDoc`.
+					// See: https://github.com/microsoft/TypeScript/issues/31267
+					{
+						/**
+						 * The column's properties.
+						 * @remarks This is a user-defined schema that can be used to store additional information about the column.
+						 */
+						props?: InsertableTreeFieldFromImplicitField<
+							UnannotateImplicitFieldSchema<TPropsSchema>
+						>;
+					}
+				: {
+						/**
+						 * The column's properties.
+						 * @remarks This is a user-defined schema that can be used to store additional information about the column.
+						 */
+						props: InsertableTreeFieldFromImplicitField<
+							UnannotateImplicitFieldSchema<TPropsSchema>
+						>;
+					});
+
+		// Modified version of `Column` that ensures the constructor (and `createFromInsertable`) are
+		// typed correctly in terms of our insertable type.
+		// This lets us be selective in our type-cast for the value returned from this function,
+		// preserving as much type-safety as we reasonably can.
+		type ColumnSchemaModifiedType = Omit<
+			// Use mapped type to omit the constructor
+			{
+				[Property in keyof typeof Column]: (typeof Column)[Property];
+			},
+			"createFromInsertable"
+		> &
+			(new (
+				parameters: InternalTreeNode | ColumnInsertableType,
+			) => Column) & {
+				createFromInsertable(parameters: ColumnInsertableType): Column;
+			};
 
 		// Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
 		// for the private brand field of TreeNode.
@@ -110,7 +204,7 @@ export namespace TableSchema {
 			/* TInsertable */ object & ColumnInsertableType,
 			/* ImplicitlyConstructable */ true,
 			/* Info */ typeof columnFields
-		> = Column;
+		> = Column as ColumnSchemaModifiedType;
 
 		return ColumnSchemaType;
 	}
@@ -120,91 +214,34 @@ export namespace TableSchema {
 	 * @sealed @system @internal
 	 */
 	export type ColumnSchemaBase<
-		TScope extends string | undefined,
-		TPropsSchema extends ImplicitAllowedTypes,
-	> = ReturnType<typeof createColumn<TScope, TPropsSchema>>;
+		TScope extends string | undefined = string | undefined,
+		TPropsSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
+	> = ReturnType<typeof TableSchema.createColumn<TScope, TPropsSchema>>;
 
 	// #endregion
 
 	// #region Row
 
 	/**
-	 * A row in a table.
-	 * @remarks Implemented by the schema class returned from {@link TableSchema.createRow}.
-	 * @sealed @internal
+	 * Base options for creating table row schema.
+	 * @remarks Includes parameters common to all row factory overloads.
+	 * @system @internal
 	 */
-	export interface IRow<
-		TCellSchema extends ImplicitAllowedTypes,
-		TPropsSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-	> {
-		/**
-		 * The unique identifier of the row.
-		 * @remarks Uniquely identifies the node within the entire tree, not just the table.
-		 */
-		readonly id: string;
-
-		/**
-		 * Gets the cell in the specified column.
-		 * @returns The cell if it exists, otherwise undefined.
-		 */
-		getCell(column: IColumn): TreeNodeFromImplicitAllowedTypes<TCellSchema> | undefined;
-		/**
-		 * Gets the cell in the specified column, denoted by column ID.
-		 * @returns The cell if it exists, otherwise undefined.
-		 */
-		getCell(columnId: string): TreeNodeFromImplicitAllowedTypes<TCellSchema> | undefined;
-
-		/**
-		 * Sets the cell in the specified column.
-		 * @remarks To remove a cell, call {@link TableSchema.IRow.(removeCell:1)} instead.
-		 */
-		setCell(
-			column: IColumn,
-			value: InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>,
-		): void;
-		/**
-		 * Sets the cell in the specified column, denoted by column ID.
-		 * @remarks To remove a cell, call {@link TableSchema.IRow.(removeCell:2)} instead.
-		 */
-		setCell(
-			columnId: string,
-			value: InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>,
-		): void;
-
-		/**
-		 * Removes the cell in the specified column.
-		 * @privateRemarks TODO: return removed cell
-		 */
-		removeCell(column: IColumn): void;
-		/**
-		 * Removes the cell in the specified column, denoted by column ID.
-		 * @privateRemarks TODO: return removed cell
-		 */
-		removeCell(columnId: string): void;
-
-		/**
-		 * User-provided row properties.
-		 */
-		get props(): TreeNodeFromImplicitAllowedTypes<TPropsSchema>;
-		set props(value: InsertableTreeNodeFromImplicitAllowedTypes<TPropsSchema>);
-	}
+	export type CreateRowOptionsBase<
+		TScope extends string | undefined = string | undefined,
+		TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	> = OptionsWithSchemaFactory<TScope> & OptionsWithCellSchema<TCell>;
 
 	/**
 	 * Factory for creating new table row schema.
 	 *
-	 * @privateRemarks
-	 * TODO:
-	 * - Add overloads to make propsSchema optional.
-	 * - Take field schema rather than node schema for `propsSchema`, in particular to allow making
-	 * the additional properties optional.
-	 *
 	 * @sealed @internal
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
-	export function createRow<
+	export function createRowInternal<
 		const TInputScope extends string | undefined,
 		const TCellSchema extends ImplicitAllowedTypes,
-		const TPropsSchema extends ImplicitAllowedTypes,
+		const TPropsSchema extends ImplicitFieldSchema,
 	>(
 		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
 		cellSchema: TCellSchema,
@@ -216,6 +253,21 @@ export namespace TableSchema {
 		type CellValueType = TreeNodeFromImplicitAllowedTypes<TCellSchema>;
 		type CellInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>;
 
+		// Note: `rowFields` is broken into two parts to work around a TypeScript bug
+		// that results in broken `.d.ts` output.
+		// See definition of `RowInsertableType` below.
+		const rowFieldsBuiltInParts = {
+			id: schemaFactory.identifier,
+			cells: schemaFactory.required(schemaFactory.map("Row.cells", cellSchema), {
+				metadata: {
+					description: "The cells of the table row, keyed by column ID.",
+				},
+			}),
+		} as const;
+		const rowFieldsPropsPart = {
+			props: propsSchema,
+		} as const;
+
 		/**
 		 * {@link Row} fields.
 		 * @remarks Extracted for re-use in returned type signature defined later in this function.
@@ -225,32 +277,34 @@ export namespace TableSchema {
 		 * Likely related to the following issue: https://github.com/microsoft/TypeScript/issues/52394
 		 */
 		const rowFields = {
-			id: schemaFactory.identifier,
-			cells: schemaFactory.map("Row.cells", cellSchema),
-			props: schemaFactory.required(propsSchema),
-		} as const;
+			...rowFieldsBuiltInParts,
+			...rowFieldsPropsPart,
+		} as const; // satisfies Record<string, ImplicitFieldSchema>;
 
 		/**
 		 * The Row schema - this is a map of Cells where the key is the column id
 		 */
 		class Row
-			extends schemaFactory.object("Row", rowFields)
-			implements IRow<TCellSchema, TPropsSchema>
+			extends schemaFactory.objectAlpha("Row", rowFields, {
+				// Will make it easier to evolve this schema in the future.
+				allowUnknownOptionalFields: true,
+			})
+			implements TableSchema.IRow<TCellSchema, TPropsSchema>
 		{
-			public getCell(columnOrId: IColumn | string): CellValueType | undefined {
+			public getCell(columnOrId: TableSchema.IColumn | string): CellValueType | undefined {
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
 				return this.cells.get(columnId) as CellValueType | undefined;
 			}
 
 			public setCell(
-				columnOrId: IColumn | string,
+				columnOrId: TableSchema.IColumn | string,
 				value: CellInsertableType | undefined,
 			): void {
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
 				this.cells.set(columnId, value);
 			}
 
-			public removeCell(columnOrId: IColumn | string): void {
+			public removeCell(columnOrId: TableSchema.IColumn | string): void {
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
 				if (!this.cells.has(columnId)) {
 					return;
@@ -260,9 +314,55 @@ export namespace TableSchema {
 		}
 
 		type RowValueType = TreeNode &
-			IRow<TCellSchema, TPropsSchema> &
+			TableSchema.IRow<TCellSchema, TPropsSchema> &
 			WithType<ScopedSchemaName<Scope, "Row">>;
-		type RowInsertableType = InsertableObjectFromSchemaRecord<typeof rowFields>;
+
+		// Note: ideally this type would just leverage `InsertableObjectFromSchemaRecord<typeof rowFields>`,
+		// but that results in broken `.d.ts` output due to a TypeScript bug.
+		// See: https://github.com/microsoft/TypeScript/issues/58688.
+		// Instead we extract and inline the typing of the "props" field here, which seems to sufficiently work around
+		// the issue.
+		// type RowInsertableType = InsertableObjectFromSchemaRecord<typeof rowFields>;
+		type RowInsertableType = InsertableObjectFromSchemaRecord<typeof rowFieldsBuiltInParts> &
+			(FieldHasDefault<TPropsSchema> extends true
+				? // Note: The docs on the below properties are copied from `IRow.props`' docs to ensure that the
+					// documentation appears in the data insertion scenario.
+					// The contents are duplicated instead of using `@inheritdoc`, as intellisense does not correctly
+					// support `@inheritDoc`.
+					// See: https://github.com/microsoft/TypeScript/issues/31267
+					{
+						/**
+						 * The row's properties.
+						 * @remarks This is a user-defined schema that can be used to store additional information
+						 * about the row.
+						 */
+						props?: InsertableTreeFieldFromImplicitField<TPropsSchema>;
+					}
+				: {
+						/**
+						 * The row's properties.
+						 * @remarks This is a user-defined schema that can be used to store additional information
+						 * about the row.
+						 */
+						props: InsertableTreeFieldFromImplicitField<TPropsSchema>;
+					});
+
+		// Modified version of `Column` that ensures the constructor (and `createFromInsertable`) are
+		// typed correctly in terms of our insertable type.
+		// This lets us be selective in our type-cast for the value returned from this function,
+		// preserving as much type-safety as we reasonably can.
+		type RowSchemaModifiedType = Omit<
+			// Use mapped type to omit the constructor
+			{
+				[Property in keyof typeof Row]: (typeof Row)[Property];
+			},
+			"createFromInsertable"
+		> &
+			(new (
+				parameters: InternalTreeNode | RowInsertableType,
+			) => Row) & {
+				createFromInsertable(parameters: RowInsertableType): Row;
+			};
 
 		// Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
 		// for the private brand field of TreeNode.
@@ -276,7 +376,7 @@ export namespace TableSchema {
 			/* TInsertable */ object & RowInsertableType,
 			/* ImplicitlyConstructable */ true,
 			/* Info */ typeof rowFields
-		> = Row;
+		> = Row as RowSchemaModifiedType;
 
 		return RowSchemaType;
 	}
@@ -286,355 +386,146 @@ export namespace TableSchema {
 	 * @sealed @system @internal
 	 */
 	export type RowSchemaBase<
-		TScope extends string | undefined,
-		TCellSchema extends ImplicitAllowedTypes,
-		TPropsSchema extends ImplicitAllowedTypes,
-	> = ReturnType<typeof createRow<TScope, TCellSchema, TPropsSchema>>;
+		TScope extends string | undefined = string | undefined,
+		TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+		TPropsSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
+	> = ReturnType<typeof TableSchema.createRow<TScope, TCellSchema, TPropsSchema>>;
 
 	// #endregion
 
 	// #region Table
 
 	/**
-	 * A key to uniquely identify a cell in a table.
-	 * @sealed @internal
+	 * Base options for creating table schema.
+	 * @remarks Includes parameters common to all table factory overloads.
+	 * @system @internal
 	 */
-	export interface CellKey {
-		/**
-		 * {@link TableSchema.IColumn.id} of the containing {@link TableSchema.IColumn}.
-		 */
-		readonly columnId: string;
-
-		/**
-		 * {@link TableSchema.IRow.id} of the containing {@link TableSchema.IRow}.
-		 */
-		readonly rowId: string;
-	}
+	export type TableFactoryOptionsBase<
+		TScope extends string | undefined = string | undefined,
+		TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	> = OptionsWithSchemaFactory<TScope> & OptionsWithCellSchema<TCell>;
 
 	/**
-	 * {@link TableSchema.ITable.insertColumn} parameters.
-	 * @sealed @internal
+	 * Factory for creating new table schema.
+	 * @system @internal
 	 */
-	export interface InsertColumnParameters<TInsertableColumn> {
-		/**
-		 * The index at which to insert the new column.
-		 * @remarks If not provided, the column will be appended to the end of the table.
-		 */
-		readonly index?: number | undefined;
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
+	export function createTableInternal<
+		const TInputScope extends string | undefined,
+		const TCellSchema extends ImplicitAllowedTypes,
+		const TColumnSchema extends ColumnSchemaBase<TInputScope> = ColumnSchemaBase<TInputScope>,
+		const TRowSchema extends RowSchemaBase<TInputScope, TCellSchema> = RowSchemaBase<
+			TInputScope,
+			TCellSchema
+		>,
+	>(
+		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
+		_cellSchema: TCellSchema,
+		columnSchema: TColumnSchema,
+		rowSchema: TRowSchema,
+	) {
+		const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
+		type Scope = ScopedSchemaName<TInputScope, typeof tableSchemaFactorySubScope>;
 
-		/**
-		 * The column to insert.
-		 */
-		readonly column: TInsertableColumn;
-	}
+		type CellValueType = TreeNodeFromImplicitAllowedTypes<TCellSchema>;
+		type CellInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>;
 
-	/**
-	 * {@link TableSchema.ITable.insertRows} parameters.
-	 * @sealed @internal
-	 */
-	export interface InsertRowsParameters<TInsertableRow> {
-		/**
-		 * The index at which to insert the new rows.
-		 * @remarks If not provided, the rows will be appended to the end of the table.
-		 */
-		readonly index?: number | undefined;
+		type ColumnValueType = TreeNodeFromImplicitAllowedTypes<TColumnSchema>;
+		type ColumnInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TColumnSchema>;
 
-		/**
-		 * The rows to insert.
-		 */
-		readonly rows: TInsertableRow[];
-	}
+		type RowValueType = TreeNodeFromImplicitAllowedTypes<TRowSchema>;
+		type RowInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TRowSchema>;
 
-	/**
-	 * {@link TableSchema.ITable.setCell} parameters.
-	 * @sealed @internal
-	 */
-	export interface SetCellParameters<TInsertableCell> {
 		/**
-		 * The key to uniquely identify a cell in a table.
+		 * {@link Table} fields.
+		 * @remarks Extracted for re-use in returned type signature defined later in this function.
+		 * The implicit typing is intentional.
 		 */
-		readonly key: CellKey;
+		const tableFields = {
+			rows: schemaFactory.array("Table.rows", rowSchema),
+			columns: schemaFactory.array("Table.columns", columnSchema),
+		} as const satisfies Record<string, ImplicitFieldSchema>;
 
 		/**
-		 * The cell to set.
+		 * The Table schema
 		 */
-		readonly cell: TInsertableCell;
-	}
+		class Table
+			extends schemaFactory.objectAlpha("Table", tableFields, {
+				// Will make it easier to evolve this schema in the future.
+				allowUnknownOptionalFields: true,
+			})
+			implements TableSchema.ITable<TCellSchema, TColumnSchema, TRowSchema>
+		{
+			public getColumn(id: string): ColumnValueType | undefined {
+				// TypeScript is unable to narrow the types correctly here, hence the casts.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				return this.columns.find((column) => (column as ColumnValueType).id === id) as
+					| ColumnValueType
+					| undefined;
+			}
 
-	/**
-	 * A table.
-	 * @sealed @internal
-	 */
-	export interface ITable<
-		TCellSchema extends ImplicitAllowedTypes,
-		TColumnSchema extends ImplicitAllowedTypes,
-		TRowSchema extends ImplicitAllowedTypes,
-	> {
-		/**
-		 * The table's columns.
-		 */
-		readonly columns: TreeArrayNode<TColumnSchema>;
+			public getRow(id: string): RowValueType | undefined {
+				// TypeScript is unable to narrow the types correctly here, hence the casts.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				return this.rows.find((_row) => (_row as RowValueType).id === id) as
+					| RowValueType
+					| undefined;
+			}
 
-		/**
-		 * The table's rows.
-		 */
-		readonly rows: TreeArrayNode<TRowSchema>;
+			public getCell(key: TableSchema.CellKey): CellValueType | undefined {
+				const { columnId, rowId } = key;
+				const row = this.getRow(rowId);
+				if (row !== undefined) {
+					const column = this.getColumn(columnId);
+					if (column !== undefined) {
+						return row.getCell(column.id);
+					}
+				}
+				// If the cell does not exist return undefined
+				return undefined;
+			}
 
-		/**
-		 * Gets a table column by its {@link TableSchema.IRow.id}.
-		 */
-		getColumn(id: string): TreeNodeFromImplicitAllowedTypes<TColumnSchema> | undefined;
+			public insertColumn({
+				column,
+				index,
+			}: TableSchema.InsertColumnParameters<ColumnInsertableType>): ColumnValueType {
+				if (index === undefined) {
+					// TypeScript is unable to narrow the types correctly here, hence the cast.
+					// See: https://github.com/microsoft/TypeScript/issues/52144
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					this.columns.insertAtEnd(column as any);
+				} else {
+					// TypeScript is unable to narrow the types correctly here, hence the cast.
+					// See: https://github.com/microsoft/TypeScript/issues/52144
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					this.columns.insertAt(index, column as any);
+				}
 
-		/**
-		 * Gets a table row by its {@link TableSchema.IRow.id}.
-		 */
-		getRow(id: string): TreeNodeFromImplicitAllowedTypes<TRowSchema> | undefined;
+				// Inserting the input node into the tree hydrates it, making it usable as a node.
+				return column as ColumnValueType;
+			}
 
-		/**
-		 * Gets a cell in the table by column and row IDs.
-		 * @param key - A key that uniquely distinguishes a cell in the table, represented as a combination of the column ID and row ID.
-		 * @privateRemarks TODO: add overload that takes row and column nodes.
-		 */
-		getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes<TCellSchema> | undefined;
-
-		/**
-		 * Inserts a column into the table.
-		 * @throws Throws an error if the column is already in the tree, or if the specified index is out of range.
-		 */
-		insertColumn(
-			params: InsertColumnParameters<
-				InsertableTreeNodeFromImplicitAllowedTypes<TColumnSchema>
-			>,
-		): TreeNodeFromImplicitAllowedTypes<TColumnSchema>;
-
-		/**
-		 * Inserts 0 or more rows into the table.
-		 * @throws Throws an error if any of the rows are already in the tree, or if the specified index is out of range.
-		 */
-		insertRows(
-			params: InsertRowsParameters<InsertableTreeNodeFromImplicitAllowedTypes<TRowSchema>>,
-		): TreeNodeFromImplicitAllowedTypes<TRowSchema>[];
-
-		/**
-		 * Sets the cell at the specified location in the table.
-		 * @remarks To remove a cell, call {@link TableSchema.ITable.removeCell} instead.
-		 * @privateRemarks TODO: add overload that takes column/row nodes?
-		 */
-		setCell(
-			params: SetCellParameters<InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>>,
-		): void;
-
-		/**
-		 * Removes the specified column from the table.
-		 * @remarks Note: this does not remove any cells from the table's rows.
-		 * @privateRemarks
-		 * TODO:
-		 * - Policy for when the column is not in the table.
-		 * - Actually remove corresponding cells from table rows.
-		 */
-		removeColumn: (column: TreeNodeFromImplicitAllowedTypes<TColumnSchema>) => void;
-
-		/**
-		 * Removes 0 or more rows from the table.
-		 * @privateRemarks TODO: policy for when 1 or more rows are not in the table.
-		 */
-		removeRows: (rows: readonly TreeNodeFromImplicitAllowedTypes<TRowSchema>[]) => void;
-
-		/**
-		 * Removes all rows from the table.
-		 */
-		removeAllRows: () => void;
-
-		/**
-		 * Removes the cell at the specified location in the table.
-		 * @privateRemarks TODO: add overload that takes column/row nodes?
-		 */
-		removeCell: (key: CellKey) => void;
-	}
-
-	/**
-	 * Factory for creating new table schema without specifying row or column schema.
-	 * @internal
-	 */
-	export function createTable<
-		const TInputScope extends string | undefined,
-		const TCell extends ImplicitAllowedTypes,
-	>(
-		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
-		_cellSchema: TCell,
-	): ReturnType<typeof createTableInternal<TInputScope, TCell>>;
-	/**
-	 * Factory for creating new table schema without specifying row schema
-	 * @internal
-	 */
-	export function createTable<
-		const TInputScope extends string | undefined,
-		const TCell extends ImplicitAllowedTypes,
-		const TColumn extends ColumnSchemaBase<TInputScope, ImplicitAllowedTypes>,
-	>(
-		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
-		_cellSchema: TCell,
-		columnSchema: TColumn,
-	): ReturnType<typeof createTableInternal<TInputScope, TCell, TColumn>>;
-	/**
-	 * Factory for creating new table schema.
-	 * @internal
-	 */
-	export function createTable<
-		const TInputScope extends string | undefined,
-		const TCell extends ImplicitAllowedTypes,
-		const TColumn extends ColumnSchemaBase<TInputScope, ImplicitAllowedTypes>,
-		const TRow extends RowSchemaBase<TInputScope, TCell, ImplicitAllowedTypes>,
-	>(
-		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
-		_cellSchema: TCell,
-		columnSchema: TColumn,
-		rowSchema: TRow,
-	): ReturnType<typeof createTableInternal<TInputScope, TCell, TColumn, TRow>>;
-	/** `createTable` implementation */
-	export function createTable<
-		const TInputScope extends string | undefined,
-		const TCell extends ImplicitAllowedTypes,
-		const TColumn extends ColumnSchemaBase<TInputScope, ImplicitAllowedTypes>,
-		const TRow extends RowSchemaBase<TInputScope, TCell, ImplicitAllowedTypes>,
-	>(
-		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
-		_cellSchema: TCell,
-		columnSchema?: TColumn,
-		rowSchema?: TRow,
-	): TreeNodeSchema {
-		const column = columnSchema ?? createColumn(inputSchemaFactory, inputSchemaFactory.null);
-		return createTableInternal(
-			inputSchemaFactory,
-			_cellSchema,
-			column as TColumn,
-			rowSchema ??
-				(createRow(inputSchemaFactory, _cellSchema, inputSchemaFactory.null) as TRow),
-		);
-	}
-
-	/**
-	 * Factory for creating new table schema.
-	 * @system @internal
-	 */
-	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
-	export function createTableInternal<
-		const TInputScope extends string | undefined,
-		const TCell extends ImplicitAllowedTypes,
-		const TColumn extends ColumnSchemaBase<
-			TInputScope,
-			ImplicitAllowedTypes
-		> = ColumnSchemaBase<TInputScope, ImplicitAllowedTypes>,
-		const TRow extends RowSchemaBase<TInputScope, TCell, ImplicitAllowedTypes> = RowSchemaBase<
-			TInputScope,
-			TCell,
-			ImplicitAllowedTypes
-		>,
-	>(
-		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
-		_cellSchema: TCell,
-		columnSchema: TColumn,
-		rowSchema: TRow,
-	) {
-		const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
-		type Scope = ScopedSchemaName<TInputScope, typeof tableSchemaFactorySubScope>;
-
-		type CellValueType = TreeNodeFromImplicitAllowedTypes<TCell>;
-		type CellInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TCell>;
-
-		type ColumnValueType = TreeNodeFromImplicitAllowedTypes<TColumn>;
-		type ColumnInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TColumn>;
-
-		type RowValueType = TreeNodeFromImplicitAllowedTypes<TRow>;
-		type RowInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TRow>;
-
-		/**
-		 * {@link Table} fields.
-		 * @remarks Extracted for re-use in returned type signature defined later in this function.
-		 * The implicit typing is intentional.
-		 */
-		const tableFields = {
-			rows: schemaFactory.array("Table.rows", rowSchema),
-			columns: schemaFactory.array("Table.columns", columnSchema),
-		} as const satisfies Record<string, ImplicitFieldSchema>;
-
-		/**
-		 * The Table schema
-		 */
-		class Table
-			extends schemaFactory.object("Table", tableFields)
-			implements ITable<TCell, TColumn, TRow>
-		{
-			public getColumn(id: string): ColumnValueType | undefined {
-				// TypeScript is unable to narrow the types correctly here, hence the casts.
-				// See: https://github.com/microsoft/TypeScript/issues/52144
-				return this.columns.find((column) => (column as ColumnValueType).id === id) as
-					| ColumnValueType
-					| undefined;
-			}
-
-			public getRow(id: string): RowValueType | undefined {
-				// TypeScript is unable to narrow the types correctly here, hence the casts.
-				// See: https://github.com/microsoft/TypeScript/issues/52144
-				return this.rows.find((_row) => (_row as RowValueType).id === id) as
-					| RowValueType
-					| undefined;
-			}
-
-			public getCell(key: CellKey): CellValueType | undefined {
-				const { columnId, rowId } = key;
-				const row = this.getRow(rowId);
-				if (row !== undefined) {
-					const column = this.getColumn(columnId);
-					if (column !== undefined) {
-						return row.getCell(column.id);
-					}
-				}
-				// If the cell does not exist return undefined
-				return undefined;
-			}
-
-			public insertColumn({
-				column,
-				index,
-			}: InsertColumnParameters<ColumnInsertableType>): ColumnValueType {
-				if (index === undefined) {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					this.columns.insertAtEnd(column as any);
-				} else {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					this.columns.insertAt(index, column as any);
-				}
-
-				// Inserting the input node into the tree hydrates it, making it usable as a node.
-				return column as ColumnValueType;
-			}
-
-			public insertRows({
-				index,
-				rows,
-			}: InsertRowsParameters<RowInsertableType>): RowValueType[] {
-				if (index === undefined) {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					this.rows.insertAtEnd(TreeArrayNode.spread(rows) as any);
-				} else {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					this.rows.insertAt(index, TreeArrayNode.spread(rows) as any);
-				}
+			public insertRows({
+				index,
+				rows,
+			}: TableSchema.InsertRowsParameters<RowInsertableType>): RowValueType[] {
+				if (index === undefined) {
+					// TypeScript is unable to narrow the types correctly here, hence the cast.
+					// See: https://github.com/microsoft/TypeScript/issues/52144
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					this.rows.insertAtEnd(TreeArrayNode.spread(rows) as any);
+				} else {
+					// TypeScript is unable to narrow the types correctly here, hence the cast.
+					// See: https://github.com/microsoft/TypeScript/issues/52144
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					this.rows.insertAt(index, TreeArrayNode.spread(rows) as any);
+				}
 
 				// Inserting the input nodes into the tree hydrates them, making them usable as nodes.
 				return rows as unknown as RowValueType[];
 			}
 
-			public setCell({ key, cell }: SetCellParameters<CellInsertableType>): void {
+			public setCell({ key, cell }: TableSchema.SetCellParameters<CellInsertableType>): void {
 				const { columnId, rowId } = key;
 				const row = this.getRow(rowId);
 				if (row !== undefined) {
@@ -679,7 +570,7 @@ export namespace TableSchema {
 				this.rows.removeRange();
 			}
 
-			public removeCell(key: CellKey): void {
+			public removeCell(key: TableSchema.CellKey): void {
 				const { columnId, rowId } = key;
 				const row = this.getRow(rowId);
 				if (row !== undefined) {
@@ -692,7 +583,7 @@ export namespace TableSchema {
 		}
 
 		type TableValueType = TreeNode &
-			ITable<TCell, TColumn, TRow> &
+			TableSchema.ITable<TCellSchema, TColumnSchema, TRowSchema> &
 			WithType<ScopedSchemaName<Scope, "Table">>;
 		type TableInsertableType = InsertableObjectFromSchemaRecord<typeof tableFields>;
 
@@ -721,16 +612,429 @@ export namespace TableSchema {
 	export type TableSchemaBase<
 		TScope extends string | undefined,
 		TCell extends ImplicitAllowedTypes,
-		TColumn extends ColumnSchemaBase<TScope, ImplicitAllowedTypes> = ColumnSchemaBase<
-			TScope,
-			ImplicitAllowedTypes
-		>,
+		TColumn extends ColumnSchemaBase<TScope> = ColumnSchemaBase<TScope>,
 		TRow extends RowSchemaBase<TScope, TCell, ImplicitAllowedTypes> = RowSchemaBase<
 			TScope,
 			TCell,
 			ImplicitAllowedTypes
 		>,
-	> = ReturnType<typeof createTable<TScope, TCell, TColumn, TRow>>;
+	> = ReturnType<typeof TableSchema.createTable<TScope, TCell, TColumn, TRow>>;
+
+	// #endregion
+}
+
+/**
+ * Contains types and factories for creating schema to represent dynamic tabular data.
+ * @privateRemarks TODO: document in more detail and add `@example`s.
+ * @internal
+ */
+export namespace TableSchema {
+	// #region Column
+
+	/**
+	 * A column in a table.
+	 * @remarks Implemented by the schema class returned from {@link TableSchema.(createColumn:2)}.
+	 * @sealed @internal
+	 */
+	export interface IColumn<
+		TProps extends ImplicitAnnotatedFieldSchema = ImplicitAnnotatedFieldSchema,
+	> {
+		/**
+		 * The unique identifier of the column.
+		 * @remarks Uniquely identifies the node within the entire tree, not just the table.
+		 */
+		readonly id: string;
+
+		/**
+		 * The column's properties.
+		 * @remarks This is a user-defined schema that can be used to store additional information about the column.
+		 * @privateRemarks
+		 * Note: these docs are duplicated on the inline type definitions in {@link createColumn}.
+		 * If you update the docs here, please also update the inline type definitions.
+		 */
+		get props(): TreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TProps>> | undefined;
+		set props(value: InsertableTreeFieldFromImplicitField<
+			UnannotateImplicitFieldSchema<TProps>
+		>);
+	}
+
+	/**
+	 * Factory for creating new table column schema.
+	 * @internal
+	 */
+	export function createColumn<const TScope extends string | undefined>({
+		schemaFactory,
+	}: System_TableSchema.CreateColumnOptionsBase<TScope>): ReturnType<
+		typeof System_TableSchema.createColumnInternal<
+			TScope,
+			FieldSchema<FieldKind.Optional, typeof SchemaFactoryAlpha.null>
+		>
+	>;
+	/**
+	 * Factory for creating new table column schema.
+	 * @internal
+	 */
+	export function createColumn<
+		const TScope extends string | undefined,
+		const TProps extends ImplicitFieldSchema,
+	>({
+		schemaFactory,
+		props,
+	}: System_TableSchema.CreateColumnOptionsBase<TScope> & {
+		/**
+		 * Optional column properties.
+		 */
+		readonly props: TProps;
+	}): ReturnType<typeof System_TableSchema.createColumnInternal<TScope, TProps>>;
+	/**
+	 * Overload implementation
+	 */
+	export function createColumn({
+		schemaFactory,
+		props = SchemaFactory.optional(SchemaFactory.null),
+	}: System_TableSchema.CreateColumnOptionsBase & {
+		readonly props?: ImplicitFieldSchema;
+	}): TreeNodeSchema {
+		return System_TableSchema.createColumnInternal(schemaFactory, props);
+	}
+
+	// #endregion
+
+	// #region Row
+
+	/**
+	 * A row in a table.
+	 * @remarks Implemented by the schema class returned from {@link TableSchema.(createRow:2)}.
+	 * @sealed @internal
+	 */
+	export interface IRow<
+		TCell extends ImplicitAllowedTypes,
+		TProps extends ImplicitAnnotatedFieldSchema = ImplicitAnnotatedFieldSchema,
+	> {
+		/**
+		 * The unique identifier of the row.
+		 * @remarks Uniquely identifies the node within the entire tree, not just the table.
+		 */
+		readonly id: string;
+
+		/**
+		 * Gets the cell in the specified column.
+		 * @returns The cell if it exists, otherwise undefined.
+		 */
+		getCell(column: IColumn): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
+		/**
+		 * Gets the cell in the specified column, denoted by column ID.
+		 * @returns The cell if it exists, otherwise undefined.
+		 */
+		getCell(columnId: string): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
+
+		/**
+		 * Sets the cell in the specified column.
+		 * @remarks To remove a cell, call {@link TableSchema.IRow.(removeCell:1)} instead.
+		 */
+		setCell(column: IColumn, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
+		/**
+		 * Sets the cell in the specified column, denoted by column ID.
+		 * @remarks To remove a cell, call {@link TableSchema.IRow.(removeCell:2)} instead.
+		 */
+		setCell(columnId: string, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
+
+		/**
+		 * Removes the cell in the specified column.
+		 * @privateRemarks TODO: return removed cell
+		 */
+		removeCell(column: IColumn): void;
+		/**
+		 * Removes the cell in the specified column, denoted by column ID.
+		 * @privateRemarks TODO: return removed cell
+		 */
+		removeCell(columnId: string): void;
+
+		/**
+		 * The row's properties.
+		 * @remarks This is a user-defined schema that can be used to store additional information about the row.
+		 * @privateRemarks
+		 * Note: these docs are duplicated on the inline type definitions in {@link createColumn}.
+		 * If you update the docs here, please also update the inline type definitions.
+		 */
+		get props(): TreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TProps>>;
+		set props(value: InsertableTreeFieldFromImplicitField<
+			UnannotateImplicitFieldSchema<TProps>
+		>);
+	}
+
+	/**
+	 * Factory for creating new table column schema.
+	 * @internal
+	 */
+	export function createRow<
+		const TScope extends string | undefined,
+		const TCell extends ImplicitAllowedTypes,
+	>({
+		schemaFactory,
+		cell,
+	}: System_TableSchema.CreateRowOptionsBase<TScope, TCell>): ReturnType<
+		typeof System_TableSchema.createRowInternal<
+			TScope,
+			TCell,
+			FieldSchema<FieldKind.Optional, typeof SchemaFactoryAlpha.null>
+		>
+	>;
+	/**
+	 * Factory for creating new table column schema.
+	 * @internal
+	 */
+	export function createRow<
+		const TScope extends string | undefined,
+		const TCell extends ImplicitAllowedTypes,
+		const TProps extends ImplicitFieldSchema,
+	>({
+		schemaFactory,
+		cell,
+		props,
+	}: System_TableSchema.CreateRowOptionsBase<TScope, TCell> & {
+		/**
+		 * Optional row properties.
+		 */
+		readonly props: TProps;
+	}): ReturnType<typeof System_TableSchema.createRowInternal<TScope, TCell, TProps>>;
+	/**
+	 * Overload implementation
+	 */
+	export function createRow({
+		schemaFactory,
+		cell,
+		props = SchemaFactory.optional(SchemaFactory.null),
+	}: System_TableSchema.CreateRowOptionsBase & {
+		readonly props?: ImplicitFieldSchema;
+	}): TreeNodeSchema {
+		return System_TableSchema.createRowInternal(schemaFactory, cell, props);
+	}
+
+	// #endregion
+
+	// #region Table
+
+	/**
+	 * A key to uniquely identify a cell in a table.
+	 * @internal
+	 */
+	export interface CellKey {
+		/**
+		 * {@link TableSchema.IColumn.id} of the containing {@link TableSchema.IColumn}.
+		 */
+		readonly columnId: string;
+
+		/**
+		 * {@link TableSchema.IRow.id} of the containing {@link TableSchema.IRow}.
+		 */
+		readonly rowId: string;
+	}
+
+	/**
+	 * {@link TableSchema.ITable.insertColumn} parameters.
+	 * @internal
+	 */
+	export interface InsertColumnParameters<TInsertableColumn> {
+		/**
+		 * The index at which to insert the new column.
+		 * @remarks If not provided, the column will be appended to the end of the table.
+		 */
+		readonly index?: number | undefined;
+
+		/**
+		 * The column to insert.
+		 */
+		readonly column: TInsertableColumn;
+	}
+
+	/**
+	 * {@link TableSchema.ITable.insertRows} parameters.
+	 * @internal
+	 */
+	export interface InsertRowsParameters<TInsertableRow> {
+		/**
+		 * The index at which to insert the new rows.
+		 * @remarks If not provided, the rows will be appended to the end of the table.
+		 */
+		readonly index?: number | undefined;
+
+		/**
+		 * The rows to insert.
+		 */
+		readonly rows: TInsertableRow[];
+	}
+
+	/**
+	 * {@link TableSchema.ITable.setCell} parameters.
+	 * @internal
+	 */
+	export interface SetCellParameters<TInsertableCell> {
+		/**
+		 * The key to uniquely identify a cell in a table.
+		 */
+		readonly key: CellKey;
+
+		/**
+		 * The cell to set.
+		 */
+		readonly cell: TInsertableCell;
+	}
+
+	/**
+	 * A table.
+	 * @sealed @internal
+	 */
+	export interface ITable<
+		TCell extends ImplicitAllowedTypes,
+		TColumn extends ImplicitAllowedTypes,
+		TRow extends ImplicitAllowedTypes,
+	> {
+		/**
+		 * The table's columns.
+		 */
+		readonly columns: TreeArrayNode<TColumn>;
+
+		/**
+		 * The table's rows.
+		 */
+		readonly rows: TreeArrayNode<TRow>;
+
+		/**
+		 * Gets a table column by its {@link TableSchema.IRow.id}.
+		 */
+		getColumn(id: string): TreeNodeFromImplicitAllowedTypes<TColumn> | undefined;
+
+		/**
+		 * Gets a table row by its {@link TableSchema.IRow.id}.
+		 */
+		getRow(id: string): TreeNodeFromImplicitAllowedTypes<TRow> | undefined;
+
+		/**
+		 * Gets a cell in the table by column and row IDs.
+		 * @param key - A key that uniquely distinguishes a cell in the table, represented as a combination of the column ID and row ID.
+		 * @privateRemarks TODO: add overload that takes row and column nodes.
+		 */
+		getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
+
+		/**
+		 * Inserts a column into the table.
+		 * @throws Throws an error if the column is already in the tree, or if the specified index is out of range.
+		 */
+		insertColumn(
+			params: InsertColumnParameters<InsertableTreeNodeFromImplicitAllowedTypes<TColumn>>,
+		): TreeNodeFromImplicitAllowedTypes<TColumn>;
+
+		/**
+		 * Inserts 0 or more rows into the table.
+		 * @throws Throws an error if any of the rows are already in the tree, or if the specified index is out of range.
+		 */
+		insertRows(
+			params: InsertRowsParameters<InsertableTreeNodeFromImplicitAllowedTypes<TRow>>,
+		): TreeNodeFromImplicitAllowedTypes<TRow>[];
+
+		/**
+		 * Sets the cell at the specified location in the table.
+		 * @remarks To remove a cell, call {@link TableSchema.ITable.removeCell} instead.
+		 * @privateRemarks TODO: add overload that takes column/row nodes?
+		 */
+		setCell(
+			params: SetCellParameters<InsertableTreeNodeFromImplicitAllowedTypes<TCell>>,
+		): void;
+
+		/**
+		 * Removes the specified column from the table.
+		 * @remarks Note: this does not remove any cells from the table's rows.
+		 * @privateRemarks
+		 * TODO:
+		 * - Policy for when the column is not in the table.
+		 * - Actually remove corresponding cells from table rows.
+		 */
+		removeColumn: (column: TreeNodeFromImplicitAllowedTypes<TColumn>) => void;
+
+		/**
+		 * Removes 0 or more rows from the table.
+		 * @privateRemarks TODO: policy for when 1 or more rows are not in the table.
+		 */
+		removeRows: (rows: readonly TreeNodeFromImplicitAllowedTypes<TRow>[]) => void;
+
+		/**
+		 * Removes all rows from the table.
+		 */
+		removeAllRows: () => void;
+
+		/**
+		 * Removes the cell at the specified location in the table.
+		 * @privateRemarks TODO: add overload that takes column/row nodes?
+		 */
+		removeCell: (key: CellKey) => void;
+	}
+
+	/**
+	 * Factory for creating new table schema without specifying row or column schema.
+	 * @internal
+	 */
+	export function createTable<
+		const TScope extends string | undefined,
+		const TCell extends ImplicitAllowedTypes,
+	>({
+		schemaFactory,
+		cell,
+	}: System_TableSchema.TableFactoryOptionsBase<TScope, TCell>): ReturnType<
+		typeof System_TableSchema.createTableInternal<TScope, TCell>
+	>;
+	/**
+	 * Factory for creating new table schema without specifying row schema.
+	 * @internal
+	 */
+	export function createTable<
+		const TScope extends string | undefined,
+		const TCell extends ImplicitAllowedTypes,
+		const TColumn extends System_TableSchema.ColumnSchemaBase<TScope>,
+	>({
+		schemaFactory,
+		cell,
+		column,
+	}: System_TableSchema.TableFactoryOptionsBase<TScope, TCell> & {
+		readonly column: TColumn;
+	}): ReturnType<typeof System_TableSchema.createTableInternal<TScope, TCell, TColumn>>;
+	/**
+	 * Factory for creating new table schema.
+	 * @internal
+	 */
+	export function createTable<
+		const TScope extends string | undefined,
+		const TCell extends ImplicitAllowedTypes,
+		const TColumn extends System_TableSchema.ColumnSchemaBase<TScope>,
+		const TRow extends System_TableSchema.RowSchemaBase<TScope, TCell>,
+	>({
+		schemaFactory,
+		cell,
+		column,
+		row,
+	}: System_TableSchema.TableFactoryOptionsBase<TScope, TCell> & {
+		readonly column: TColumn;
+		readonly row: TRow;
+	}): ReturnType<typeof System_TableSchema.createTableInternal<TScope, TCell, TColumn, TRow>>;
+	/**
+	 * Overload implementation
+	 */
+	export function createTable({
+		schemaFactory,
+		cell,
+		column = createColumn({
+			schemaFactory,
+		}),
+		row = createRow({
+			schemaFactory,
+			cell,
+		}),
+	}: System_TableSchema.TableFactoryOptionsBase & {
+		readonly column?: System_TableSchema.ColumnSchemaBase;
+		readonly row?: System_TableSchema.RowSchemaBase;
+	}): TreeNodeSchema {
+		return System_TableSchema.createTableInternal(schemaFactory, cell, column, row);
+	}
 
 	// #endregion
 }