add javadocs

domino-ui/src/main/java/org/dominokit/domino/ui/tree/HasActiveNode.java

@@ -15,10 +15,39 @@
  */
 package org.dominokit.domino.ui.tree;
 
+/**
+ * An interface for tree structures or nodes that track a single "active" (e.g., focused) node.
+ *
+ * <p>Commonly, "active" refers to a highlighted node in the tree. Depending on the implementation,
+ * activation may also trigger actions like expanding/collapsing or scrolling the node into view.
+ *
+ * @param <V> the data value type held by the node
+ * @param <N> the node type (e.g., a subclass of {@link TreeNode})
+ * @param <S> the type representing the overall selection or active state
+ */
 public interface HasActiveNode<V, N extends TreeNode<V, N, S>, S> {
+
+  /**
+   * Sets the specified node as the active node in this tree or subtree. Behaviors may include
+   * highlighting the node, deactivating previously active nodes, or other custom responses.
+   *
+   * @param node the node to activate
+   */
   void setActiveNode(N node);
 
+  /**
+   * Sets the specified node as the active node, optionally suppressing event notifications or other
+   * side effects.
+   *
+   * @param node the node to activate
+   * @param silent {@code true} to suppress event notifications, {@code false} to allow them
+   */
   void setActiveNode(N node, boolean silent);
 
+  /**
+   * Retrieves the node currently marked as active, if any.
+   *
+   * @return the active node, or {@code null} if none is active
+   */
   N getActiveNode();
 }

domino-ui/src/main/java/org/dominokit/domino/ui/tree/IsParentNode.java

@@ -17,20 +17,96 @@
 
 import java.util.Optional;
 
+/**
+ * An interface representing a parent node in a tree-like structure. Defines the minimal contract
+ * for a node that can hold children, expand to show them, and integrate into a root tree hierarchy.
+ *
+ * <p>Methods:
+ *
+ * <ul>
+ *   <li>{@link #getRootNode()} - obtains the {@link RootNode} that this node ultimately belongs to
+ *   <li>{@link #expandNode()} / {@link #expandNode(boolean)} - expands this node (and optionally
+ *       parent nodes)
+ *   <li>{@link #getFilter()} - retrieves the filter logic used to determine visibility/matching
+ *       (e.g., for search)
+ *   <li>{@link #getParent()} - returns the parent node, if any
+ *   <li>{@link #removeNode(TreeNode)} - removes a child node
+ *   <li>{@link #getValue()} / {@link #setValue(Object)} - manages the data value associated with
+ *       this node
+ * </ul>
+ *
+ * <p>This interface also extends {@link HasActiveNode} to provide for activation (focus/selection)
+ * logic at the parent level.
+ *
+ * @param <V> the type of data value or model object stored in nodes
+ * @param <N> the node type (e.g., a concrete subclass of {@link TreeNode})
+ * @param <S> the selection type, often the same as the node type or a collection of nodes
+ */
 public interface IsParentNode<V, N extends TreeNode<V, N, S>, S> extends HasActiveNode<V, N, S> {
+
+  /**
+   * Returns the root of the tree that this node is ultimately part of. The root node typically
+   * manages high-level tree behaviors (e.g., auto-collapse, icon suppliers).
+   *
+   * @return the root node of this tree hierarchy
+   */
   RootNode<V, N, S> getRootNode();
 
+  /**
+   * Expands this node to show its children (if any). Behavior may vary depending on the tree
+   * configuration (e.g., auto-collapse of siblings, etc.).
+   *
+   * @return this node (for method chaining)
+   */
   IsParentNode<V, N, S> expandNode();
 
+  /**
+   * Expands this node, optionally also expanding all parent nodes up the hierarchy. Useful for
+   * ensuring a path is fully visible from the root down to this node.
+   *
+   * @param expandParent if true, also expands parent nodes
+   * @return this node (for method chaining)
+   */
   IsParentNode<V, N, S> expandNode(boolean expandParent);
 
+  /**
+   * Retrieves the filter logic that determines if this node (and its subtree) match certain
+   * criteria (e.g., a search token). Often implemented at the root node, then inherited by
+   * children.
+   *
+   * @return the current filter logic for this node
+   */
   TreeItemFilter<N> getFilter();
 
+  /**
+   * Returns an optional reference to this node's parent, if it exists. If the node is at the root
+   * level, the result is typically empty (no parent).
+   *
+   * @return an {@link Optional} containing the parent node
+   */
   Optional<IsParentNode<V, N, S>> getParent();
 
+  /**
+   * Removes a child node from this node's subtree. If the node is not a direct child,
+   * implementations may ignore or handle it differently.
+   *
+   * @param node the node to remove
+   */
   void removeNode(N node);
 
+  /**
+   * Retrieves the data value associated with this node, if any. This is typically the model object
+   * or identifier linked to the node's display.
+   *
+   * @return the data value for this node
+   */
   V getValue();
 
+  /**
+   * Sets the data value associated with this node. Useful for changing the underlying model object
+   * without recreating the node.
+   *
+   * @param value the new data value
+   */
   void setValue(V value);
 }

domino-ui/src/main/java/org/dominokit/domino/ui/tree/RootNode.java

@@ -15,14 +15,64 @@
  */
 package org.dominokit.domino.ui.tree;
 
+/**
+ * Represents the root of a tree structure, providing common behaviors and configurations for all
+ * nodes within the tree.
+ *
+ * <p>Notable capabilities include:
+ *
+ * <ul>
+ *   <li>Tracking and managing an active node (see {@link HasActiveNode})
+ *   <li>Controlling whether nodes automatically collapse or expand under certain conditions
+ *   <li>Supplying icons for nodes via a {@link NodeIconSupplier}
+ *   <li>Receiving notifications when a node's active state or selection changes
+ * </ul>
+ *
+ * @param <V> the type of data value associated with each node
+ * @param <N> the node (tree item) type
+ * @param <S> the type representing the selection (often the node type or a list of nodes)
+ */
 public interface RootNode<V, N extends TreeNode<V, N, S>, S> extends HasActiveNode<V, N, S> {
+
+  /**
+   * Indicates whether parent nodes should automatically collapse when a new node is activated or
+   * expanded.
+   *
+   * @return true if automatic collapse is enabled, false otherwise
+   */
   boolean isAutoCollapse();
 
+  /**
+   * Indicates whether nodes should automatically expand when they match a search or filtering
+   * criterion (e.g., "found" nodes in a search).
+   *
+   * @return true if automatic expansion of found nodes is enabled, false otherwise
+   */
   boolean isAutoExpandFound();
 
+  /**
+   * Retrieves the {@link NodeIconSupplier} responsible for providing icons to each node within the
+   * tree.
+   *
+   * @return a {@link NodeIconSupplier} instance
+   */
   NodeIconSupplier<V, N, S> getIconSupplier();
 
+  /**
+   * Called when the active node changes within this tree (e.g., a node is activated or
+   * re-activated).
+   *
+   * @param node the node that is now active
+   * @param selection the current selection in the tree
+   * @param silent true if the change should not trigger user-facing events, false otherwise
+   */
   default void onActiveNodeChanged(N node, S selection, boolean silent) {}
 
+  /**
+   * Called when a node is deselected (or changes its selection state) in this tree.
+   *
+   * @param source the node that triggered the deselection event
+   * @param selection the current selection in the tree after deselection
+   */
   void onDeselectionChanged(N source, S selection);
 }