feat: DH-19652: API for Expand to Depth on a Hierarchical Table

[cpwright]

No description provided.

[github-actions]

No docs changes detected for 0724725

[Copilot]

Pull request overview

Adds “expand to depth” support for hierarchical table snapshots and exposes it through the web client TreeTable API, enabling controlled, depth-limited expansion behavior beyond existing expand / expand-all directives.

Changes:

• Introduces a new key-table action encoding for “expand to depth” (base + depth) in the HierarchicalTable API.
• Extends the hierarchical snapshot traversal logic to support depth-limited auto-expansion, and adds snapshot tests covering multiple expand-to-depth scenarios.
• Adds a TreeTable.expandToDepth(...) JS API method and refactors duplicated row-resolution/action-setting logic.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
web/client-api/src/main/java/io/deephaven/web/client/api/tree/JsTreeTable.java	Adds JS-facing expandToDepth and refactors row/action handling helpers
engine/api/src/main/java/io/deephaven/engine/table/hierarchical/HierarchicalTable.java	Defines expand-to-depth action encoding + helper method and updates snapshot docs
engine/table/src/main/java/io/deephaven/engine/table/impl/hierarchical/HierarchicalTableImpl.java	Implements expand-to-depth semantics in snapshot traversal and directive parsing
engine/table/src/test/java/io/deephaven/engine/table/impl/TestHierarchicalTableSnapshots.java	Adds tests validating expand-all and expand-to-depth behaviors (including overrides)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

ExpandToDepth currently sets expandingDepthRemaining = expandToDepth, but Linkage decrements the counter when descending. With this combination, an ExpandToDepth(2) directive will still auto-expand grandchildren (one level deeper than the tests / JS API description imply). Consider initializing the remaining counter as expandToDepth - 1 (and validating expandToDepth >= 1) so that depth=2 expands the directive node and its immediate children, but not deeper levels unless explicitly directed.

Suggested change

	// Set the remaining depth counter; Linkage visits will decrement as we descend levels
	expandingDepthRemaining = levelExpandable ? expandToDepth : 0;
	// Validate requested depth and set the remaining depth counter below this node;
	// Linkage visits will decrement as we descend levels
	Assert.assertion(expandToDepth >= 1, "expandToDepth >= 1",
	"ExpandToDepth must be at least 1");
	expandingDepthRemaining = levelExpandable ? (expandToDepth - 1) : 0;

[Copilot]

The new expand-to-depth Javadoc describes depth as "levels below the directive node", but the JS API and tests in this PR treat depth as total expansion levels starting at the directive node (e.g. depth=1 == plain expand). Please align this documentation (and the expandToDepthAction parameter docs) to the implemented semantics to avoid client confusion and off-by-one usage errors.

Suggested change

	* {@code KEY_TABLE_ACTION_EXPAND_TO_DEPTH_BASE + depth}, where {@code depth >= 2}. A depth of 1 is equivalent to
	* {@link #KEY_TABLE_ACTION_EXPAND}, and an unlimited depth is equivalent to {@link #KEY_TABLE_ACTION_EXPAND_ALL}.
	* <p>
	* The node will be expanded, and its descendants will be expanded up to {@code depth} levels below the directive
	* node, unless they are included in the key table with a {@link #KEY_TABLE_ACTION_CONTRACT contraction} or their
	* direct parent has a directive with action {@link #KEY_TABLE_ACTION_EXPAND}.
	*/
	byte KEY_TABLE_ACTION_EXPAND_TO_DEPTH_BASE = 0b0100_0000;
	/**
	* Create a key table action byte value for expanding a node to a specific depth.
	*
	* @param depth The number of levels to expand below the directive node (must be &gt;= 2 and &lt;= 63)
	* {@code KEY_TABLE_ACTION_EXPAND_TO_DEPTH_BASE + depth}, where {@code depth >= 2}. Here, {@code depth} is the
	* total number of expansion levels starting at the directive node (i.e., the directive node itself is level 1).
	* A depth of 1 is equivalent to {@link #KEY_TABLE_ACTION_EXPAND}, and an unlimited depth is equivalent to
	* {@link #KEY_TABLE_ACTION_EXPAND_ALL}.
	* <p>
	* The node will be expanded, and its descendants will be expanded up to {@code depth - 1} levels below the
	* directive node, unless they are included in the key table with a {@link #KEY_TABLE_ACTION_CONTRACT contraction}
	* or their direct parent has a directive with action {@link #KEY_TABLE_ACTION_EXPAND}.
	*/
	byte KEY_TABLE_ACTION_EXPAND_TO_DEPTH_BASE = 0b0100_0000;
	/**
	* Create a key table action byte value for expanding a node to a specific depth.
	* <p>
	* The {@code depth} value represents the total number of expansion levels starting at the directive node
	* (i.e., the directive node itself is level 1). A depth of 1 is equivalent to {@link #KEY_TABLE_ACTION_EXPAND};
	* this method encodes depths {@code >= 2} using {@link #KEY_TABLE_ACTION_EXPAND_TO_DEPTH_BASE}.
	*
	* @param depth The total number of expansion levels starting at the directive node (must be &gt;= 2 and &lt;= 63)

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[niloc132]

Let's add a JS API test for this in HierarchicalTableTestGwt