fix #885 Add the ability to insert a menu item(s) in a specific index

domino-ui/src/main/java/org/dominokit/domino/ui/forms/suggest/AbstractSelect.java

@@ -231,6 +231,20 @@ public C appendChild(O option) {
     return (C) this;
   }
 
+  /**
+   * Insert the specified option in the specified index.
+   *
+   * @param index The desired location index.
+   * @param option The option to be added to the select.
+   * @return an instance of the concrete class.
+   */
+  public C insertChild(int index, O option) {
+    if (nonNull(option)) {
+      optionsMenu.insertChild(index, option.getMenuItem());
+    }
+    return (C) this;
+  }
+
   /**
    * Appends a collection of options to the select.
    *
@@ -244,6 +258,25 @@ public C appendOptions(Collection<O> options) {
     return (C) this;
   }
 
+  /**
+   * Insert a collection of options starting from the provided index.
+   *
+   * @param index The insert starting index
+   * @param options The collection of options to be added to the select.
+   * @return an instance of the concrete class.
+   */
+  public C insertOptions(int index, Collection<O> options) {
+    if (nonNull(options)) {
+      int[] i = new int[] {index};
+      options.forEach(
+          o -> {
+            insertChild(i[0], o);
+            i[0] = i[0]++;
+          });
+    }
+    return (C) this;
+  }
+
   /**
    * Appends a series of options to the select.
    *
@@ -257,6 +290,20 @@ public C appendOptions(O... options) {
     return (C) this;
   }
 
+  /**
+   * Insert a series of options to the select at the provided index.
+   *
+   * @param index The starting insert index.
+   * @param options The options to be added to the select.
+   * @return an instance of the concrete class.
+   */
+  public C insertOptions(int index, O... options) {
+    if (nonNull(options)) {
+      insertOptions(index, Arrays.asList(options));
+    }
+    return (C) this;
+  }
+
   /**
    * Maps the specified item using the provided mapper function and appends it as an option to the
    * select.
@@ -269,6 +316,18 @@ public <I> C appendItem(Function<I, O> mapper, I item) {
     return appendChild(mapper.apply(item));
   }
 
+  /**
+   * Maps the specified item using the provided mapper function and insert it at the provided index
+   *
+   * @param index The index
+   * @param mapper The function to map the item to an option.
+   * @param item The item to be mapped and added as an option to the select.
+   * @return an instance of the concrete class.
+   */
+  public <I> C insertItem(int index, Function<I, O> mapper, I item) {
+    return insertChild(index, mapper.apply(item));
+  }
+
   /**
    * Maps each item in the provided collection using the given mapper function and appends them as
    * options to the select.
@@ -282,6 +341,25 @@ public <I> C appendItems(Function<I, O> mapper, Collection<I> items) {
     return (C) this;
   }
 
+  /**
+   * Maps each item in the provided collection using the given mapper function and insert them
+   * starting from the provided index.
+   *
+   * @param index The starting insert index.
+   * @param mapper The function to map each item to an option.
+   * @param items The collection of items to be mapped and added as options to the select.
+   * @return an instance of the concrete class.
+   */
+  public <I> C insertItems(int index, Function<I, O> mapper, Collection<I> items) {
+    int[] i = new int[] {index};
+    items.forEach(
+        item -> {
+          insertItem(i[0], mapper, item);
+          i[0] = i[0]++;
+        });
+    return (C) this;
+  }
+
   /**
    * Maps each item in the provided series using the given mapper function and appends them as
    * options to the select.
@@ -295,6 +373,20 @@ public <I> C appendItems(Function<I, O> mapper, I... items) {
     return (C) this;
   }
 
+  /**
+   * Maps each item in the provided series using the given mapper function and insert them starting
+   * from the provided index.
+   *
+   * @param index insert starting index.
+   * @param mapper The function to map each item to an option.
+   * @param items The items to be mapped and added as options to the select.
+   * @return an instance of the concrete class.
+   */
+  public <I> C insertItems(int index, Function<I, O> mapper, I... items) {
+    insertItems(index, mapper, Arrays.asList(items));
+    return (C) this;
+  }
+
   /**
    * Appends the specified separator to the select.
    *
@@ -306,6 +398,18 @@ public <I> C appendChild(Separator separator) {
     return (C) this;
   }
 
+  /**
+   * insert the specified separator to the select at the provided index.
+   *
+   * @param index the insert index.
+   * @param separator The separator to be added between options in the select.
+   * @return an instance of the concrete class.
+   */
+  public <I> C insertChild(int index, Separator separator) {
+    optionsMenu.insertChild(index, separator);
+    return (C) this;
+  }
+
   /**
    * Retrieves the current placeholder text from the select.
    *
@@ -1001,7 +1105,9 @@ public C withOptionsMenu(ChildHandler<C, Menu<T>> handler) {
   public C setMissingItemHandler(MissingOptionHandler<C, E, T, O> missingOptionHandler) {
     if (nonNull(missingOptionHandler)) {
       optionsMenu.setMissingItemHandler(
-          (token, menu) -> missingOptionHandler.onMissingItem((C) this, token, menu::appendChild));
+          (token, menu) ->
+              missingOptionHandler.onMissingItem(
+                  (C) this, token, option -> appendChild((O) option)));
     } else {
       optionsMenu.setMissingItemHandler(null);
     }
@@ -1029,6 +1135,17 @@ public C removeOption(O option) {
     return (C) this;
   }
 
+  /**
+   * Removes a specified option from the select component.
+   *
+   * @param index the index of the option to be removed.
+   * @return an instance of the concrete class.
+   */
+  public C removeOptionAt(int index) {
+    AbstractMenuItem<T> menuItem = optionsMenu.getMenuItems().get(index);
+    return removeOption(OptionMeta.<T, E, O>get(menuItem).get().getOption());
+  }
+
   /**
    * Removes a collection of options from the select component.
    *

domino-ui/src/main/java/org/dominokit/domino/ui/menu/Menu.java

@@ -412,12 +412,47 @@ public Menu<V> appendChild(AbstractMenuItem<V> menuItem) {
     if (nonNull(menuItem)) {
       menuItemsList.appendChild(menuItem);
       menuItems.add(menuItem);
-      menuItem.setParent(this);
-      onItemAdded(menuItem);
+      afterAddItem(menuItem);
     }
     return this;
   }
 
+  /**
+   * Inserts a menu item to the menu at the specified index, the index should be within the valid
+   * range otherwise an exception is thrown.
+   *
+   * @param index The index to insert the menu item at.
+   * @param menuItem The menu item to be added.
+   * @return The current Menu instance.
+   */
+  public Menu<V> insertChild(int index, AbstractMenuItem<V> menuItem) {
+    if (nonNull(menuItem)) {
+      if (index < 0 || (index > 0 && index >= menuItemsList.getChildElementCount())) {
+        throw new IndexOutOfBoundsException(
+            "Could not insert menu item at index ["
+                + index
+                + "], index out of range [0,"
+                + (menuItemsList.getChildElementCount() - 1)
+                + "]");
+      }
+      if (menuItemsList.getChildElementCount() > 0) {
+        DominoElement<Element> elementDominoElement = menuItemsList.childElements().get(index);
+        menuItemsList.insertBefore(menuItem, elementDominoElement);
+        menuItems.add(index, menuItem);
+      } else {
+        menuItemsList.appendChild(menuItem);
+        menuItems.add(menuItem);
+      }
+      afterAddItem(menuItem);
+    }
+    return this;
+  }
+
+  private void afterAddItem(AbstractMenuItem<V> menuItem) {
+    menuItem.setParent(this);
+    onItemAdded(menuItem);
+  }
+
   void onItemAdded(AbstractMenuItem<V> menuItem) {
     onAddItemHandlers.forEach(handler -> handler.onAdded(this, menuItem));
   }
@@ -441,6 +476,42 @@ public <I extends AbstractMenuItem<V>> Menu<V> appendGroup(
     return this;
   }
 
+  /**
+   * Inserts a menu items group to the menu at the specified index, the index should be within the
+   * valid range otherwise an exception is thrown.
+   *
+   * @param index The index to insert the menu items group at.
+   * @param <I> The type of the abstract menu item.
+   * @param menuGroup The menu items group to be added.
+   * @param groupHandler The handler for the menu items group.
+   * @return The current Menu instance.
+   */
+  public <I extends AbstractMenuItem<V>> Menu<V> insertGroup(
+      int index, MenuItemsGroup<V> menuGroup, MenuItemsGroupHandler<V, I> groupHandler) {
+    if (nonNull(menuGroup)) {
+
+      if (index < 0 || (index > 0 && index >= menuItemsList.getChildElementCount())) {
+        throw new IndexOutOfBoundsException(
+            "Could not insert menu item at index ["
+                + index
+                + "], index out of range [0,"
+                + (menuItemsList.getChildElementCount() - 1)
+                + "]");
+      }
+      if (menuItemsList.getChildElementCount() > 0) {
+        DominoElement<Element> elementDominoElement = menuItemsList.childElements().get(index);
+        menuItemsList.insertBefore(menuGroup, elementDominoElement);
+        menuItems.add(index, menuGroup);
+      } else {
+        menuItemsList.appendChild(menuGroup);
+        menuItems.add(menuGroup);
+      }
+      menuGroup.setParent(this);
+      groupHandler.handle(menuGroup);
+    }
+    return this;
+  }
+
   /**
    * Removes a menu item from the menu.
    *
@@ -455,6 +526,16 @@ public Menu<V> removeItem(AbstractMenuItem<V> menuItem) {
     return this;
   }
 
+  /**
+   * Removes a menu item from the menu at the specified index.
+   *
+   * @param index the index of the menu item to be removed.
+   * @return The current Menu instance.
+   */
+  public Menu<V> removeItemAt(int index) {
+    return removeItem(menuItems.get(index));
+  }
+
   /**
    * Removes all items and sub-items from the menu.
    *
@@ -479,6 +560,36 @@ public Menu<V> appendChild(Separator separator) {
     return this;
   }
 
+  /**
+   * Inserts a separator to the menu at the specified index, the index should be within the valid
+   * range otherwise an exception is thrown.
+   *
+   * @param index The index to insert the separator at.
+   * @param separator The separator to be added.
+   * @return The current Menu instance.
+   */
+  public Menu<V> insertChild(int index, Separator separator) {
+    if (nonNull(separator)) {
+      if (index < 0 || (index > 0 && index >= menuItemsList.getChildElementCount())) {
+        throw new IndexOutOfBoundsException(
+            "Could not insert menu item at index ["
+                + index
+                + "], index out of range [0,"
+                + (menuItemsList.getChildElementCount() - 1)
+                + "]");
+      }
+
+      if (menuItemsList.getChildElementCount() > 0) {
+        DominoElement<Element> elementDominoElement = menuItemsList.childElements().get(index);
+        menuItemsList.insertBefore(separator, elementDominoElement);
+      } else {
+        this.menuItemsList.appendChild(separator.addCss(dui_menu_separator));
+      }
+    }
+
+    return this;
+  }
+
   /**
    * {@inheritDoc}
    *