docs: Enhance JSDoc for atomic moves and focus preservation (#8615)

Author: tobiu

src/container/Base.mjs

@@ -618,9 +618,19 @@ class Container extends Component {
     }
 
     /**
-     * Inserts an item or array of items at a specific index
+     * Inserts an item or array of items at a specific index.
+     *
+     * **Atomic Moves:**
+     * If the `item` is an existing `Neo.component.Base` instance that already has a parent container
+     * within the same browser window, this method performs an **atomic move**.
+     * 1. The item is silently removed from its old parent (without triggering a DOM removal).
+     * 2. The item is inserted into this container.
+     * 3. This container updates, sending an `insertNode` delta.
+     * 4. The `DeltaUpdates` system detects the existing DOM node and moves it physically, preserving
+     *    DOM state such as focus, input values, and iframe content.
+     *
      * @param {Number} index
-     * @param {Array|Object} item
+     * @param {Array|Object|Neo.component.Base} item
      * @param {Boolean} [silent=false]
      * @param {Boolean} [removeFromPreviousParent=true]
      * @returns {Neo.component.Base|Neo.component.Base[]}

src/main/DeltaUpdates.mjs

@@ -430,6 +430,11 @@ class DeltaUpdates extends Base {
      * It performs a direct sibling swap when an element is immediately followed by its target position,
      * which is necessary to prevent attempting to replace a node with itself.
      *
+     * **Focus Preservation:**
+     * In WebKit/Blink browsers (Chrome, Safari), reparenting a focused element causes it to lose focus.
+     * This method detects if the moved node contains the active element and automatically restores focus
+     * immediately after the move operation to ensure a seamless user experience.
+     *
      * @param {Object} delta
      * @param {String} delta.id       The ID of the DOM node to move.
      * @param {Number} delta.index    The physical index at which to insert the node within the target parent's childNodes.

src/worker/App.mjs

@@ -500,6 +500,10 @@ class App extends Base {
 
     /**
      * Moves a component to a new parent container via remote method access.
+     * This operation is **atomic** and state-preserving when moving within the same browser window.
+     * It relies on `Neo.container.Base.insert` to handle the silent removal from the old parent,
+     * ensuring that the DOM node is physically moved rather than destroyed and recreated.
+     *
      * @param {Object} data
      * @param {String} data.id The id of the component to move.
      * @param {String} data.parentId The id of the new parent container.