feat: async state

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/context/IFOpenContext.java

@@ -4,6 +4,7 @@
 import me.devnatan.inventoryframework.ViewConfig;
 import me.devnatan.inventoryframework.ViewConfigBuilder;
 import me.devnatan.inventoryframework.ViewContainer;
+import me.devnatan.inventoryframework.state.AsyncState;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -34,6 +35,18 @@ public interface IFOpenContext extends IFConfinedContext {
      */
     void waitUntil(@NotNull CompletableFuture<Void> task);
 
+    /**
+     * Waits for a asynchronous state to be complete before ending this opening context and
+     * transitioning to the rendering context (waits to show the inventory to the player).
+     * <p>
+     * <b>This API is experimental and is not subject to the general compatibility guarantees such API
+     * may be changed or may be removed completely in any further release.</b>
+     *
+     * @param state The state to wait before opening the inventory.
+     */
+    @ApiStatus.Experimental
+    void waitFor(@NotNull AsyncState<?> state);
+
     /**
      * Whether opening the container to the viewer has been cancelled.
      *

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/state/AsyncState.java

@@ -0,0 +1,3 @@
+package me.devnatan.inventoryframework.state;
+
+public interface AsyncState<T> extends State<T> {}

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/state/State.java

@@ -16,6 +16,11 @@
  */
 public interface State<T> {
 
+    /**
+     * <p><b><i> This is an internal inventory-framework API that should not be used from outside of
+     * this library. No compatibility guarantees are provided. </i></b>
+     */
+    @ApiStatus.Internal
     AtomicLong ids = new AtomicLong();
 
     /**
@@ -51,8 +56,12 @@ public interface State<T> {
     /**
      * Generates a new state id.
      *
+     * <p><b><i> This is an internal inventory-framework API that should not be used from outside of
+     * this library. No compatibility guarantees are provided. </i></b>
+     *
      * @return A new unique state id.
      */
+    @ApiStatus.Internal
     static long next() {
         return ids.getAndIncrement();
     }

inventory-framework-api/src/main/java/me/devnatan/inventoryframework/state/StateAccess.java

@@ -139,6 +139,40 @@ public interface StateAccess<
      */
     <T> State<T> lazyState(@NotNull Supplier<T> computation);
 
+    /**
+     * Creates an immutable lazy asynchronous state.
+     * <p>
+     * This method expects you to return a {@link CompletableFuture} in <code>computation</code>
+     * parameter so elements in the view that are watching that state can hook to it and wait
+     * until that future gets completed to proceed with whatever they are willing to do.
+     * <p>
+     * <b>This API is experimental and is not subject to the general compatibility guarantees such API
+     * may be changed or may be removed completely in any further release.</b>
+     *
+     * @param computation The value factory.
+     * @param <T>         The state value type.
+     * @return A new lazy asynchronous state instance.
+     */
+    @ApiStatus.Experimental
+    <T> State<T> lazyAsyncState(@NotNull Supplier<CompletableFuture<T>> computation);
+
+    /**
+     * Creates an immutable lazy asynchronous state.
+     * <p>
+     * This method expects you to return a {@link CompletableFuture} in <code>computation</code>
+     * parameter so elements in the view that are watching that state can hook to it and wait
+     * until that future gets completed to proceed with whatever they are willing to do.
+     * <p>
+     * <b>This API is experimental and is not subject to the general compatibility guarantees such API
+     * may be changed or may be removed completely in any further release.</b>
+     *
+     * @param computation The value factory.
+     * @param <T>         The state value type.
+     * @return A new lazy asynchronous state instance.
+     */
+    @ApiStatus.Experimental
+    <T> State<T> lazyAsyncState(@NotNull Function<Context, CompletableFuture<T>> computation);
+
     /**
      * Creates a mutable {@link #lazyState(Function) lazy state} whose value is always computed
      * from the initial data set by its {@link StateValueHost}.

inventory-framework-platform-bukkit/src/main/java/me/devnatan/inventoryframework/context/OpenContext.java

@@ -13,6 +13,7 @@
 import me.devnatan.inventoryframework.ViewConfigBuilder;
 import me.devnatan.inventoryframework.ViewContainer;
 import me.devnatan.inventoryframework.Viewer;
+import me.devnatan.inventoryframework.state.AsyncState;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
@@ -31,6 +32,7 @@ public class OpenContext extends PlatformConfinedContext implements IFOpenContex
 
     // --- User Provided ---
     private CompletableFuture<Void> waitTask;
+    private AsyncState<?> waitState;
     private ViewConfigBuilder inheritedConfigBuilder;
 
     // --- Properties ---
@@ -139,6 +141,11 @@ public final void waitUntil(@NotNull CompletableFuture<Void> task) {
         this.waitTask = task;
     }
 
+    @Override
+    public void waitFor(@NotNull AsyncState<?> state) {
+        this.waitState = state;
+    }
+
     @Override
     public final @NotNull ViewConfig getConfig() {
         return inheritedConfigBuilder == null

inventory-framework-platform-minestom/src/main/kotlin/me/devnatan/inventoryframework/context/OpenContext.kt

@@ -6,6 +6,7 @@ import me.devnatan.inventoryframework.ViewConfig
 import me.devnatan.inventoryframework.ViewConfigBuilder
 import me.devnatan.inventoryframework.ViewContainer
 import me.devnatan.inventoryframework.Viewer
+import me.devnatan.inventoryframework.state.AsyncState
 import net.kyori.adventure.text.Component
 import net.minestom.server.entity.Player
 import org.jetbrains.annotations.ApiStatus
@@ -44,6 +45,7 @@ class OpenContext
         // --- User Provided ---
 
         private var waitTask: CompletableFuture<Void>? = null
+        private var waitState: AsyncState<*>? = null
         private var inheritedConfigBuilder: ViewConfigBuilder? = null
 
         // --- Properties ---
@@ -109,6 +111,10 @@ class OpenContext
             this.waitTask = task
         }
 
+        override fun waitFor(state: AsyncState<*>) {
+            this.waitState = state
+        }
+
         override fun getConfig(): ViewConfig =
             if (inheritedConfigBuilder == null) {
                 getRoot().config

inventory-framework-platform/src/main/java/me/devnatan/inventoryframework/PlatformView.java

@@ -664,6 +664,18 @@ public final <T> State<T> lazyState(@NotNull Supplier<T> computation) {
         return stateAccess.lazyState(computation);
     }
 
+    @Override
+    public <T> State<T> lazyAsyncState(@NotNull Supplier<CompletableFuture<T>> computation) {
+        requireNotInitialized();
+        return stateAccess.lazyAsyncState(computation);
+    }
+
+    @Override
+    public <T> State<T> lazyAsyncState(@NotNull Function<TContext, CompletableFuture<T>> computation) {
+        requireNotInitialized();
+        return stateAccess.lazyAsyncState(computation);
+    }
+
     @Override
     public final <T> MutableState<T> initialState() {
         requireNotInitialized();