Definitive pagination implementation (#328)

Author: devnatan

api/src/main/java/me/devnatan/inventoryframework/RootView.java

@@ -64,7 +64,7 @@ public interface RootView extends VirtualView, Iterable<IFContext> {
      * @return The pipeline for this view.
      */
     @NotNull
-    Pipeline<? super VirtualView> getPipeline();
+    Pipeline<VirtualView> getPipeline();
 
     void open(@NotNull Viewer viewer);
 

api/src/main/java/me/devnatan/inventoryframework/ViewConfigBuilder.java

@@ -79,6 +79,11 @@ public ViewConfigBuilder size(int size) {
         return this;
     }
 
+    // TODO needs documentation
+    public ViewConfigBuilder maxSize() {
+        throw new UnsupportedOperationException("TODO");
+    }
+
     /**
      * Add a modifier to this setting.
      *

api/src/main/java/me/devnatan/inventoryframework/component/Component.java

@@ -38,7 +38,6 @@ public interface Component extends VirtualView {
      *
      * @return The interaction handler for this component.
      */
-    @NotNull
     InteractionHandler getInteractionHandler();
 
     /**
@@ -55,6 +54,16 @@ public interface Component extends VirtualView {
      */
     void updated(@NotNull IFSlotRenderContext context);
 
+    /**
+     * Determines if this component should be updated.
+     * <p>
+     * This is a simple precondition to make checking the need for component updates more efficient,
+     * checking your own conditions before going to more complex methods.
+     *
+     * @return {@code true} if this component should be updated or {@code false} otherwise.
+     */
+    boolean shouldBeUpdated();
+
     /**
      * Clears this component from the given context.
      *

api/src/main/java/me/devnatan/inventoryframework/component/ItemComponent.java

@@ -62,6 +62,11 @@ public void updated(@NotNull IFSlotRenderContext context) {
         updateHandler.accept(context);
     }
 
+    @Override
+    public boolean shouldBeUpdated() {
+        return getRenderHandler() != null;
+    }
+
     @Override
     public void clear(@NotNull IFContext context) {
         context.getContainer().removeItem(getPosition());

api/src/main/java/me/devnatan/inventoryframework/component/Pagination.java

@@ -1,7 +1,6 @@
 package me.devnatan.inventoryframework.component;
 
 import me.devnatan.inventoryframework.state.StateValueHost;
-import org.jetbrains.annotations.Nullable;
 
 /**
  * Pagination is a host to multiple components that can be paginated, essentially it is a {@link
@@ -32,6 +31,20 @@ public interface Pagination extends ComponentComposition {
      */
     int currentPageIndex();
 
+    /**
+     * The number of the next page.
+     *
+     * @return The number of the next page at least {@link #lastPage()}.
+     */
+    int nextPage();
+
+    /**
+     * The index of the next page.
+     *
+     * @return The index of the next page at least {@link #lastPageIndex()}.
+     */
+    int nextPageIndex();
+
     /**
      * The number of the last page.
      * <p>
@@ -65,18 +78,20 @@ public interface Pagination extends ComponentComposition {
     boolean isLastPage();
 
     /**
-     * Checks for pages before the current page.
+     * Checks if a page exists.
      *
-     * @return {@code true} if there are previous pages or {@code false} otherwise.
+     * @param pageIndex The page index to check.
+     * @return If exists a page with the specified index.
      */
-    boolean hasPreviousPage();
+    boolean hasPage(int pageIndex);
 
     /**
-     * Checks for pages after the current page.
+     * Switches to a specific page index.
      *
-     * @return {@code true} if there are next pages or {@code false} otherwise.
+     * @param pageIndex The page index to switch to.
+     * @throws IndexOutOfBoundsException If a page with the specified index is not found.
      */
-    boolean hasNextPage();
+    void switchTo(int pageIndex);
 
     /**
      * Advances to the next page if available.
@@ -108,6 +123,8 @@ public interface Pagination extends ComponentComposition {
      *
      * @return The layout character target if set or {@code null}.
      */
-    @Nullable
-    String getLayoutTarget();
+    char getLayoutTarget();
+
+    // TODO documentation
+    boolean isDynamic();
 }

api/src/main/java/me/devnatan/inventoryframework/component/PaginationElementFactory.java

@@ -0,0 +1,7 @@
+package me.devnatan.inventoryframework.component;
+
+@FunctionalInterface
+public interface PaginationElementFactory<T> {
+
+    ComponentFactory create(int index, int slot, T value);
+}

api/src/main/java/me/devnatan/inventoryframework/context/IFConfinedContext.java

@@ -4,8 +4,30 @@
 import me.devnatan.inventoryframework.Viewer;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * A confined context is a context derivation wholly subordinated to a parent context that
+ * represents a closed scope of execution containing only one viewer, that is, when a player
+ * interacts with an item and throws a click event a subordinate confined context with that player
+ * as {@link Viewer} of a {@link IFSlotClickContext} is launched.
+ */
 public interface IFConfinedContext extends IFContext {
 
+    /**
+     * The parent context of this confined context.
+     * <p>
+     * Not all confined contexts have a parent, in which case getting the parent will return the
+     * instance of that context itself.
+     *
+     * @return The parent context or this.
+     */
+    @NotNull
+    IFContext getParent();
+
+    /**
+     * The viewer in current scope of execution.
+     *
+     * @return The {@link Viewer} in the current scope of execution.
+     */
     @NotNull
     Viewer getViewer();
 
@@ -15,7 +37,7 @@ public interface IFConfinedContext extends IFContext {
     void closeForPlayer();
 
     /**
-     * Opens a new view only for the player that is in the execution context of that context.
+     * Opens a new view only for the player that is in the current scope of execution.
      * <p>
      * This context will be immediately invalidated if there are no viewers left after opening.
      *
@@ -24,7 +46,7 @@ public interface IFConfinedContext extends IFContext {
     void openForPlayer(Class<? extends RootView> other);
 
     /**
-     * Updates the container title for everyone that's viewing it.
+     * Updates the container title only for the player current scope of execution.
      *
      * <p>This should not be used before the container is opened, if you need to set the __initial
      * title__ use {@link IFOpenContext#modifyConfig()} on open handler instead.
@@ -38,8 +60,8 @@ public interface IFConfinedContext extends IFContext {
     void updateTitleForPlayer(@NotNull String title);
 
     /**
-     * Updates the container title to all viewers in this context, to the initially defined title.
-     * Must be used after {@link #updateTitleForPlayer(String)} to take effect.
+     * Resets the container title only for the player current scope of execution to the initially
+     * defined title. Must be used after {@link #updateTitleForPlayer(String)} to take effect.
      */
     void resetTitleForPlayer();
 }

api/src/main/java/me/devnatan/inventoryframework/context/IFRenderContext.java

@@ -4,11 +4,13 @@
 import java.util.function.BiFunction;
 import me.devnatan.inventoryframework.component.ComponentFactory;
 import me.devnatan.inventoryframework.internal.LayoutSlot;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.UnmodifiableView;
 
 public interface IFRenderContext extends IFConfinedContext {
 
+    @NotNull
     IFContext getParent();
 
     @NotNull
@@ -19,6 +21,9 @@ public interface IFRenderContext extends IFConfinedContext {
     @UnmodifiableView
     List<LayoutSlot> getLayoutSlots();
 
+    @ApiStatus.Internal
+    void addLayoutSlot(@NotNull LayoutSlot layoutSlot);
+
     @NotNull
     @UnmodifiableView
     List<BiFunction<Integer, Integer, ComponentFactory>> getAvailableSlotsFactories();

api/src/main/java/me/devnatan/inventoryframework/feature/Feature.java

@@ -16,7 +16,6 @@
  * which will be taken when the Feature is referenced, and the class of the feature itself is
  * private while its key is public for later installation.
  *
- * <h3>Configuration</h3>
  * <p>
  * Since features are immutable at runtime, there needs to be a way to pre-define their initial
  * values in case it is necessary for them to act together with these values, defined by the user,
@@ -30,7 +29,6 @@
  *  final class SampleFeatureConfig {}
  * </code></pre>
  *
- * <h3>Preventing instance leak</h3>
  * <p>
  * It is important to note that features are singleton instances and can only be modified (by
  * themselves) once in their entire lifecycle, which is during their installation. The

api/src/main/java/me/devnatan/inventoryframework/internal/ElementFactory.java

@@ -5,6 +5,7 @@
 import me.devnatan.inventoryframework.ViewType;
 import me.devnatan.inventoryframework.Viewer;
 import me.devnatan.inventoryframework.component.Component;
+import me.devnatan.inventoryframework.component.ComponentBuilder;
 import me.devnatan.inventoryframework.context.IFContext;
 import me.devnatan.inventoryframework.context.IFSlotContext;
 import me.devnatan.inventoryframework.logging.Logger;
@@ -63,5 +64,12 @@ public abstract <T extends IFSlotContext> T createSlotContext(
             @NotNull IFContext parent,
             @NotNull Class<?> kind);
 
+    /**
+     * Creates a new platform builder instance.
+     *
+     * @return A new platform builder instance.
+     */
+    public abstract ComponentBuilder<?> createComponentBuilder();
+
     public abstract boolean worksInCurrentPlatform();
 }