diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java
index 1b3036c..3ed49f2 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java
@@ -4,6 +4,7 @@
import org.bukkit.event.inventory.InventoryClickEvent;
import org.bukkit.event.inventory.InventoryDragEvent;
import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import space.maxus.flare.ui.Composable;
@@ -15,14 +16,30 @@
import java.util.*;
+/**
+ * A composition is a collection of multiple components, composed by relative coordinates.
+ *
+ * See more in Flare docs: Composition
+ */
public interface Composition extends Composable, Configurable {
+ /**
+ * Constructs a composition out of an array of packed composables
+ * @param comps Composable elements to be included
+ * @return A new composition
+ * @see space.maxus.flare.ui.ComposableLike#inside(ComposableSpace)
+ */
@Contract("_ -> new")
static @NotNull Composition of(PackedComposable... comps) {
return new ExplicitComposition(Arrays.asList(comps));
}
+ @ApiStatus.Internal
List fitIn(ComposableSpace space);
+ /**
+ * Returns all composable elements inside this composition
+ * @return All composable elements inside this composition
+ */
List children();
@Override
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java
index a38bdcb..ce3fa0d 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java
@@ -3,6 +3,7 @@
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.ToString;
+import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull;
import space.maxus.flare.item.ItemProvider;
import space.maxus.flare.ui.Composable;
@@ -17,26 +18,76 @@
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.function.Consumer;
+/**
+ * A modal is a composable that opens an inner frame on click.
+ *
+ * See more in Flare docs: Modal
+ *
+ * @see Modals
+ */
public interface Modal extends ProviderRendered, Configurable, Disable {
+ /**
+ * Constructs a new modal
+ * @param provider Item provider for modal
+ * @param dimensions Dimensions of the modal window
+ * @param initializer The modal frame configurator
+ * @return A new modal
+ */
static @NotNull Modal of(@NotNull ItemProvider provider, Dimensions dimensions, Consumer initializer) {
return new ModalImpl(provider, "A Flare Modal", initializer, dimensions, false);
}
+ /**
+ * Constructs a new modal builder
+ * @param provider Item provider for this modal
+ * @return A new modal builder
+ */
static @NotNull Builder builder(@NotNull ItemProvider provider) {
return new ModalImpl.Builder(provider);
}
+ /**
+ * Returns the frame of this modal
+ * @return The frame of this modal
+ */
ModalFrame getFrame();
+ /**
+ * A builder for modals
+ */
interface Builder extends ComposableLike {
+ /**
+ * Sets the title of the modal frame
+ * @param title The title of the modal frame
+ * @return This builder
+ */
@NotNull Builder title(@NotNull String title);
+ /**
+ * Sets the dimensions of the modal frame
+ * @param dimensions Dimensions of the modal frame
+ * @return This builder
+ */
@NotNull Builder dimensions(@NotNull Dimensions dimensions);
+ /**
+ * Sets the modal frame initializer
+ * @param initializer The initializer for the modal frame
+ * @return This builder
+ */
@NotNull Builder initializer(@NotNull Consumer initializer);
+ /**
+ * Disables the modal button
+ * @param disabled Disabled state
+ * @return This builder
+ */
@NotNull Builder disabled(boolean disabled);
+ /**
+ * Builds this modal
+ * @return Built modal
+ */
@NotNull Modal build();
@Override
@@ -45,11 +96,18 @@ default Composable asComposable() {
}
}
+ /**
+ * The modal frame
+ */
@EqualsAndHashCode(callSuper = true)
@ToString
abstract class ModalFrame extends PageFrame {
+ @ApiStatus.Internal
@Getter
protected final AtomicBoolean isClosing = new AtomicBoolean(false);
+ /**
+ * The parent modal used
+ */
@Getter
protected Modal parent;
@@ -64,6 +122,7 @@ public void close() {
}
}
+ @ApiStatus.Internal
record ModalProps(Modal self, Dimensions dimensions, String title, Consumer initializer) {
}
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java
index 552a9b8..4a519b0 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java
@@ -12,27 +12,58 @@
import space.maxus.flare.ui.compose.Placeholder;
import space.maxus.flare.ui.space.Slot;
+/**
+ * Contains certain utility modals
+ */
@UtilityClass
public class Modals {
+ /**
+ * A Yes/No modal
+ */
@Builder
public static final class YesNoModal implements ComposableLike {
+ /**
+ * The name of the modal
+ */
@Builder.Default
private final String name = "Modal";
+ /**
+ * The description of the modal button
+ */
@Builder.Default
private final String description = "Opens a modal";
+ /**
+ * The name of the decline button
+ */
@Builder.Default
private final String declineName = "Decline";
+ /**
+ * The name of the accept button
+ */
@Builder.Default
private final String acceptName = "Accept";
+ /**
+ * Handler for when the accept button is clicked
+ */
@Builder.Default
private final Runnable onAccept = () -> {
};
+ /**
+ * Handler for when the decline button
+ */
@Builder.Default
private final Runnable onDecline = () -> {
};
+ /**
+ * Extra information in the modal
+ */
@Builder.Default
private final @Nullable String extraInformation = null;
+ /**
+ * Converts this modal into a modal builder
+ * @return The modal builder
+ */
@SuppressWarnings("ConstantValue")
public Modal.@NotNull Builder asBuilder() {
return yesOrNoModalBuilder(
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java
index c5c5baa..eae2384 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java
@@ -17,7 +17,17 @@
import space.maxus.flare.ui.page.Pagination;
import space.maxus.flare.util.SafeComputable;
+/**
+ * Pagination display is used to display pagination state.
+ *
+ * See more in Flare docs: PaginationDisplay
+ */
public interface PaginationDisplay extends Composable, Configurable {
+ /**
+ * Returns the item builder for arrow forward button
+ * @param disabled Whether the button is disabled
+ * @return Item builder
+ */
static @NotNull ItemStackBuilder arrowForwardButton(boolean disabled) {
return Items.builder(Material.PLAYER_HEAD)
.hideAllFlags()
@@ -34,6 +44,11 @@ public interface PaginationDisplay extends Composable, Configurable pagination) {
return new PaginationDisplayImpl(pagination, 0, null, null, null, null);
}
+ /**
+ * Creates a new pagination display
+ * @param pagination The pagination used
+ * @param idx Currently selected page index
+ * @return New pagination display
+ */
static @NotNull PaginationDisplay of(Pagination> pagination, int idx) {
return new PaginationDisplayImpl(pagination, 0, null, null, null, null);
}
+ /**
+ * Creates a new pagination builder
+ * @param pagination The pagination to use
+ * @return A new pagination builder
+ */
static @NotNull Builder builder(Pagination> pagination) {
return new PaginationDisplayImpl.Builder(pagination);
}
+ /**
+ * Gets the current pagination
+ * @return The currently used pagination
+ */
Pagination> getPagination();
+ /**
+ * Returns the reactive state of the selected page index
+ * @return The reactive state of the selected page index
+ */
ReactiveState selectedIndex();
+ /**
+ * Returns the reactive state of the selected page frame
+ * @return The reactive state of the selected page frame
+ */
ReactiveState selectedFrame();
+ /**
+ * Switches to another page index
+ * @param page Page index to switch to
+ */
default void switchPage(int page) {
getPagination().switchPage(viewer(), page);
}
+ /**
+ * A pagination display builder
+ */
interface Builder extends ComposableLike {
+ /**
+ * Sets the currently selected page index
+ * @param index Index to be set
+ * @return This builder
+ */
@NotNull Builder selectedIndex(int index);
+ /**
+ * Sets the back button item provider
+ * @param back The provider to use
+ * @return This builder
+ */
@NotNull Builder backButton(@Nullable ItemProvider back);
+ /**
+ * Sets the forward button item provider
+ * @param forward The provider to use
+ * @return This builder
+ */
@NotNull Builder forwardButton(@Nullable ItemProvider forward);
+ /**
+ * Sets the selected page item builder
+ * @param page The provider to be set
+ * @return This builder
+ */
@NotNull Builder selectedPage(@Nullable SafeComputable, ItemStack> page);
+ /**
+ * Sets the unselected page item builder
+ * @param page The provider to be set
+ * @return This builder
+ */
@NotNull Builder unselectedPage(@Nullable SafeComputable, ItemStack> page);
+ /**
+ * Builds this pagination display
+ * @return Built pagination display
+ */
@NotNull PaginationDisplay build();
@Override
diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java
index b7909d7..8f91953 100644
--- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java
+++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java
@@ -14,7 +14,18 @@
import space.maxus.flare.ui.compose.Configurable;
import space.maxus.flare.ui.page.Pagination;
+/**
+ * Tabulation is used to display pagination state.
+ *
+ * See more in Flare docs: Tabulation
+ */
public interface Tabulation extends Composable, Configurable {
+ /**
+ * Returns the unselected item builder
+ * @param idx The page index
+ * @param frame The page frame
+ * @return Unselected item builder
+ */
static ItemStackBuilder unselectedItemBuilder(int idx, Frame frame) {
return Items.builder(Material.PLAYER_HEAD)
.headSkin("eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzNlNGI1MzNlNGJhMmRmZjdjMGZhOTBmNjdlOGJlZjM2NDI4YjZjYjA2YzQ1MjYyNjMxYjBiMjVkYjg1YiJ9fX0=")
@@ -24,6 +35,12 @@ static ItemStackBuilder unselectedItemBuilder(int idx, Frame frame) {
.hideAllFlags();
}
+ /**
+ * Returns the selected item builder
+ * @param idx The page index
+ * @param frame The page frame
+ * @return Selected item builder
+ */
static ItemStackBuilder selectedItemBuilder(int idx, Frame frame) {
return Items.builder(Material.PLAYER_HEAD)
.headSkin("eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNWZmMzE0MzFkNjQ1ODdmZjZlZjk4YzA2NzU4MTA2ODFmOGMxM2JmOTZmNTFkOWNiMDdlZDc4NTJiMmZmZDEifX19")
@@ -32,14 +49,33 @@ static ItemStackBuilder selectedItemBuilder(int idx, Frame frame) {
.hideAllFlags();
}
+ /**
+ * Constructs a new tabulation
+ * @param pagination The pagination to use
+ * @return Constructed tabulation
+ */
static @NotNull Tabulation of(Pagination> pagination) {
return new TabulationImpl(pagination, null, null, 0);
}
+ /**
+ * Constructs a new tabulation
+ * @param pagination The pagination to use
+ * @param idx Currently selected page index
+ * @return Constructed tabulation
+ */
static @NotNull Tabulation of(Pagination> pagination, int idx) {
return new TabulationImpl(pagination, null, null, idx);
}
+ /**
+ * Constructs a new tabulation
+ * @param pagination The pagination to use
+ * @param selected Builder for selected page button
+ * @param unselected Builder for unselected page button
+ * @param idx Currently selected page index
+ * @return Constructed tabulation
+ */
static @NotNull Tabulation of(
Pagination> pagination,
@Nullable Computable, ItemStack> selected,
@@ -49,12 +85,28 @@ static ItemStackBuilder selectedItemBuilder(int idx, Frame frame) {
return new TabulationImpl(pagination, selected, unselected, idx);
}
+ /**
+ * Returns bound pagination
+ * @return Bound pagination
+ */
Pagination> getPagination();
+ /**
+ * Returns selected page index state
+ * @return Selected page index state
+ */
ReactiveState selectedIndex();
+ /**
+ * Returns selected page frame state
+ * @return Selected page frame state
+ */
ReactiveState selectedFrame();
+ /**
+ * Switches current page to the given page
+ * @param page Page index to switch to
+ */
default void switchPage(int page) {
getPagination().switchPage(viewer(), page);
}