Feature: Tree expansion state

src/Umbraco.Web.UI.Client/src/packages/core/tree/default/default-tree.context.ts

@@ -3,6 +3,8 @@ import type { UmbTreeRepository } from '../data/tree-repository.interface.js';
 import type { UmbTreeContext } from '../tree-context.interface.js';
 import type { UmbTreeRootItemsRequestArgs } from '../data/types.js';
 import type { ManifestTree } from '../extensions/types.js';
+import { UmbTreeExpansionManager } from '../expansion-manager/index.js';
+import type { UmbTreeExpansionModel } from '../expansion-manager/types.js';
 import { UMB_TREE_CONTEXT } from './default-tree.context-token.js';
 import { type UmbActionEventContext, UMB_ACTION_EVENT_CONTEXT } from '@umbraco-cms/backoffice/action';
 import { type ManifestRepository, umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
@@ -38,10 +40,14 @@ export class UmbDefaultTreeContext<
 	public filter?: (item: TreeItemType) => boolean = () => true;
 	public readonly selection = new UmbSelectionManager(this._host);
 	public readonly pagination = new UmbPaginationManager();
+	public readonly expansion = new UmbTreeExpansionManager(this._host);
 
 	#hideTreeRoot = new UmbBooleanState(false);
 	hideTreeRoot = this.#hideTreeRoot.asObservable();
 
+	#expandTreeRoot = new UmbBooleanState(undefined);
+	expandTreeRoot = this.#expandTreeRoot.asObservable();
+
 	#startNode = new UmbObjectState<UmbTreeStartNode | undefined>(undefined);
 	startNode = this.#startNode.asObservable();
 
@@ -156,6 +162,10 @@ export class UmbDefaultTreeContext<
 		if (data) {
 			this.#treeRoot.setValue(data);
 			this.pagination.setTotalItems(1);
+
+			if (this.getExpandTreeRoot()) {
+				this.#toggleTreeRootExpansion(true);
+			}
 		}
 	}
 
@@ -277,6 +287,56 @@ export class UmbDefaultTreeContext<
 		return this.#additionalRequestArgs.getValue();
 	}
 
+	/**
+	 * Sets the expansion state
+	 * @param {UmbTreeExpansionModel} data - The expansion state
+	 * @returns {void}
+	 * @memberof UmbDefaultTreeContext
+	 */
+	setExpansion(data: UmbTreeExpansionModel): void {
+		this.expansion.setExpansion(data);
+	}
+
+	/**
+	 * Gets the expansion state
+	 * @returns {UmbTreeExpansionModel} - The expansion state
+	 * @memberof UmbDefaultTreeContext
+	 */
+	getExpansion(): UmbTreeExpansionModel {
+		return this.expansion.getExpansion();
+	}
+
+	/**
+	 * Sets the expandTreeRoot config
+	 * @param {boolean} expandTreeRoot - Whether to expand the tree root
+	 * @memberof UmbDefaultTreeContext
+	 */
+	setExpandTreeRoot(expandTreeRoot: boolean) {
+		this.#expandTreeRoot.setValue(expandTreeRoot);
+		this.#toggleTreeRootExpansion(expandTreeRoot);
+	}
+
+	/**
+	 * Gets the expandTreeRoot config
+	 * @returns {boolean | undefined} - Whether to expand the tree root
+	 * @memberof UmbDefaultTreeContext
+	 */
+	getExpandTreeRoot(): boolean | undefined {
+		return this.#expandTreeRoot.getValue();
+	}
+
+	#toggleTreeRootExpansion(expand: boolean) {
+		const treeRoot = this.#treeRoot.getValue();
+		if (!treeRoot) return;
+		const treeRootEntity = { entityType: treeRoot.entityType, unique: treeRoot.unique };
+
+		if (expand) {
+			this.expansion.expandItem(treeRootEntity);
+		} else {
+			this.expansion.collapseItem(treeRootEntity);
+		}
+	}
+
 	#resetTree() {
 		this.#treeRoot.setValue(undefined);
 		this.#rootItems.setValue([]);

src/Umbraco.Web.UI.Client/src/packages/core/tree/default/default-tree.element.ts

@@ -5,6 +5,7 @@
 	UmbTreeSelectionConfiguration,
 	UmbTreeStartNode,
 } from '../types.js';
+import type { UmbTreeExpansionModel } from '../expansion-manager/types.js';
 import type { UmbDefaultTreeContext } from './default-tree.context.js';
 import { UMB_TREE_CONTEXT } from './default-tree.context-token.js';
 import type { PropertyValueMap } from '@umbraco-cms/backoffice/external/lit';
@@ -28,6 +29,9 @@
 	@property({ type: Boolean, attribute: false })
 	hideTreeRoot: boolean = false;
 
+	@property({ type: Boolean, attribute: false })
+	expandTreeRoot: boolean = false;
+
 	@property({ type: Object, attribute: false })
 	startNode?: UmbTreeStartNode;
 
@@ -40,6 +44,9 @@
 	@property({ attribute: false })
 	filter: (item: UmbTreeItemModelBase) => boolean = () => true;
 
+	@property({ attribute: false })
+	expansion: UmbTreeExpansionModel = [];
+
 	@state()
 	private _rootItems: UmbTreeItemModel[] = [];
 
@@ -92,23 +99,35 @@
 			this.#treeContext!.setHideTreeRoot(this.hideTreeRoot);
 		}
 
+		if (_changedProperties.has('expandTreeRoot')) {
+			this.#treeContext!.setExpandTreeRoot(this.expandTreeRoot);
+		}
+
 		if (_changedProperties.has('foldersOnly')) {
 			this.#treeContext!.setFoldersOnly(this.foldersOnly ?? false);
 		}
 
 		if (_changedProperties.has('selectableFilter')) {
 			this.#treeContext!.selectableFilter = this.selectableFilter;
 		}
 
 		if (_changedProperties.has('filter')) {
 			this.#treeContext!.filter = this.filter;
 		}
+
+		if (_changedProperties.has('expansion')) {
+			this.#treeContext!.setExpansion(this.expansion);
+		}
 	}
 
 	getSelection() {
 		return this.#treeContext?.selection.getSelection();
 	}
 
+	getExpansion() {
+		return this.#treeContext?.expansion.getExpansion();
+	}
+
 	override render() {
 		return html` ${this.#renderTreeRoot()} ${this.#renderRootItems()}`;
 	}

src/Umbraco.Web.UI.Client/src/packages/core/tree/entity-actions/duplicate-to/modal/duplicate-to-modal.element.ts

@@ -32,6 +32,7 @@ export class UmbDuplicateToModalElement extends UmbModalBaseElement<UmbDuplicate
 						alias=${this.data.treeAlias}
 						.props=${{
 							foldersOnly: this.data?.foldersOnly,
+							expandTreeRoot: true,
 						}}
 						@selection-change=${this.#onTreeSelectionChange}></umb-tree>
 				</uui-box>

src/Umbraco.Web.UI.Client/src/packages/core/tree/entity-actions/move/move-to.action.ts

@@ -16,6 +16,7 @@ export class UmbMoveToEntityAction extends UmbEntityActionBase<MetaEntityActionM
 			data: {
 				treeAlias: this.args.meta.treeAlias,
 				foldersOnly: this.args.meta.foldersOnly,
+				expandTreeRoot: true,
 				pickableFilter: (treeItem) => treeItem.unique !== this.args.unique,
 			},
 		});

src/Umbraco.Web.UI.Client/src/packages/core/tree/expansion-manager/index.ts

@@ -0,0 +1 @@
+export * from './tree-expansion-manager.js';

src/Umbraco.Web.UI.Client/src/packages/core/tree/expansion-manager/tree-expansion-manager.test.ts

@@ -0,0 +1,107 @@
+import { UmbTreeExpansionManager } from './tree-expansion-manager.js';
+import { expect } from '@open-wc/testing';
+import { Observable } from '@umbraco-cms/backoffice/external/rxjs';
+import { customElement } from '@umbraco-cms/backoffice/external/lit';
+import { UmbControllerHostElementMixin } from '@umbraco-cms/backoffice/controller-api';
+
+@customElement('test-my-controller-host')
+class UmbTestControllerHostElement extends UmbControllerHostElementMixin(HTMLElement) {}
+
+describe('UmbTreeExpansionManager', () => {
+	let manager: UmbTreeExpansionManager;
+	const item = { entityType: 'test', unique: '123' };
+	const item2 = { entityType: 'test', unique: '456' };
+
+	beforeEach(() => {
+		const hostElement = new UmbTestControllerHostElement();
+		manager = new UmbTreeExpansionManager(hostElement);
+	});
+
+	describe('Public API', () => {
+		describe('properties', () => {
+			it('has an expansion property', () => {
+				expect(manager).to.have.property('expansion').to.be.an.instanceOf(Observable);
+			});
+		});
+
+		describe('methods', () => {
+			it('has an isExpanded method', () => {
+				expect(manager).to.have.property('isExpanded').that.is.a('function');
+			});
+
+			it('has a setExpansion method', () => {
+				expect(manager).to.have.property('setExpansion').that.is.a('function');
+			});
+
+			it('has a getExpansion method', () => {
+				expect(manager).to.have.property('getExpansion').that.is.a('function');
+			});
+
+			it('has a expandItem method', () => {
+				expect(manager).to.have.property('expandItem').that.is.a('function');
+			});
+
+			it('has a collapseItem method', () => {
+				expect(manager).to.have.property('collapseItem').that.is.a('function');
+			});
+
+			it('has a collapseAll method', () => {
+				expect(manager).to.have.property('collapseAll').that.is.a('function');
+			});
+		});
+	});
+
+	describe('isExpanded', () => {
+		it('checks if an item is expanded', (done) => {
+			manager.setExpansion([item]);
+			const isExpanded = manager.isExpanded(item);
+			expect(isExpanded).to.be.an.instanceOf(Observable);
+			manager.isExpanded(item).subscribe((value) => {
+				console.log('VALUE', value);
+				expect(value).to.be.true;
+				done();
+			});
+		});
+	});
+
+	describe('setExpansion', () => {
+		it('sets the expansion state', () => {
+			const expansion = [item];
+			manager.setExpansion(expansion);
+			expect(manager.getExpansion()).to.deep.equal(expansion);
+		});
+	});
+
+	describe('getExpansion', () => {
+		it('gets the expansion state', () => {
+			const expansion = [item];
+			manager.setExpansion(expansion);
+			expect(manager.getExpansion()).to.deep.equal(expansion);
+		});
+	});
+
+	describe('expandItem', () => {
+		it('expands an item', async () => {
+			await manager.expandItem(item);
+			expect(manager.getExpansion()).to.deep.equal([item]);
+		});
+	});
+
+	describe('collapseItem', () => {
+		it('collapses an item', async () => {
+			await manager.expandItem(item);
+			expect(manager.getExpansion()).to.deep.equal([item]);
+			manager.collapseItem(item);
+			expect(manager.getExpansion()).to.deep.equal([]);
+		});
+	});
+
+	describe('collapseAll', () => {
+		it('collapses all items', () => {
+			manager.setExpansion([item, item2]);
+			expect(manager.getExpansion()).to.deep.equal([item, item2]);
+			manager.collapseAll();
+			expect(manager.getExpansion()).to.deep.equal([]);
+		});
+	});
+});

src/Umbraco.Web.UI.Client/src/packages/core/tree/expansion-manager/tree-expansion-manager.ts

@@ -0,0 +1,81 @@
+import type { UmbTreeExpansionModel } from './types.js';
+import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
+import type { UmbEntityModel } from '@umbraco-cms/backoffice/entity';
+import { UmbArrayState, type Observable } from '@umbraco-cms/backoffice/observable-api';
+
+/**
+ * Manages the expansion state of a tree
+ * @exports
+ * @class UmbTreeExpansionManager
+ * @augments {UmbControllerBase}
+ */
+export class UmbTreeExpansionManager extends UmbControllerBase {
+	#expansion = new UmbArrayState<UmbEntityModel>([], (x) => x.unique);
+	expansion = this.#expansion.asObservable();
+
+	/**
+	 * Checks if an entity is expanded
+	 * @param {UmbEntityModel} entity The entity to check
+	 * @param {string} entity.entityType The entity type
+	 * @param {string} entity.unique The unique key
+	 * @returns {Observable<boolean>} True if the entity is expanded
+	 * @memberof UmbTreeExpansionManager
+	 */
+	isExpanded(entity: UmbEntityModel): Observable<boolean> {
+		return this.#expansion.asObservablePart((entries) =>
+			entries?.some((entry) => entry.entityType === entity.entityType && entry.unique === entity.unique),
+		);
+	}
+
+	/**
+	 * Sets the expansion state
+	 * @param {UmbTreeExpansionModel | undefined} expansion The expansion state
+	 * @memberof UmbTreeExpansionManager
+	 * @returns {void}
+	 */
+	setExpansion(expansion: UmbTreeExpansionModel): void {
+		this.#expansion.setValue(expansion);
+	}
+
+	/**
+	 * Gets the expansion state
+	 * @memberof UmbTreeExpansionManager
+	 * @returns {UmbTreeExpansionModel} The expansion state
+	 */
+	getExpansion(): UmbTreeExpansionModel {
+		return this.#expansion.getValue();
+	}
+
+	/**
+	 * Opens a child tree item
+	 * @param {UmbEntityModel} entity The entity to open
+	 * @param {string} entity.entityType The entity type
+	 * @param {string} entity.unique The unique key
+	 * @memberof UmbTreeExpansionManager
+	 * @returns {Promise<void>}
+	 */
+	public async expandItem(entity: UmbEntityModel): Promise<void> {
+		this.#expansion.appendOne(entity);
+	}
+
+	/**
+	 * Closes a child tree item
+	 * @param {UmbEntityModel} entity The entity to close
+	 * @param {string} entity.entityType The entity type
+	 * @param {string} entity.unique The unique key
+	 * @memberof UmbTreeExpansionManager
+	 * @returns {Promise<void>}
+	 */
+	public async collapseItem(entity: UmbEntityModel): Promise<void> {
+		this.#expansion.filter((x) => x.entityType !== entity.entityType || x.unique !== entity.unique);
+	}
+
+	/**
+	 * Closes all child tree items
+	 * @memberof UmbTreeExpansionManager
+	 * @returns {Promise<void>}
+	 */
+	public async collapseAll(): Promise<void> {
+		this.#expansion.setValue([]);
+	}
+}

src/Umbraco.Web.UI.Client/src/packages/core/tree/expansion-manager/types.ts

@@ -0,0 +1,3 @@
+import type { UmbEntityModel } from '@umbraco-cms/backoffice/entity';
+
+export type UmbTreeExpansionModel = Array<UmbEntityModel>;